1 .. |with| replace:: *with*
2 .. |withs| replace:: *with*\ s
3 .. |withed| replace:: *with*\ ed
4 .. |withing| replace:: *with*\ ing
6 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
10 .. _Building_Executable_Programs_With_GNAT:
12 **************************************
13 Building Executable Programs with GNAT
14 **************************************
16 This chapter describes first the gnatmake tool
17 (:ref:`The_GNAT_Make_Program_gnatmake`),
18 which automatically determines the set of sources
19 needed by an Ada compilation unit and executes the necessary
20 (re)compilations, binding and linking.
21 It also explains how to use each tool individually: the
22 compiler (gcc, see :ref:`Compiling_with_gcc`),
23 binder (gnatbind, see :ref:`Binding_with_gnatbind`),
24 and linker (gnatlink, see :ref:`Linking_with_gnatlink`)
25 to build executable programs.
26 Finally, this chapter provides examples of
27 how to make use of the general GNU make mechanism
28 in a GNAT context (see :ref:`Using_the_GNU_make_Utility`).
32 For building large systems with components possibly written
33 in different languages (such as Ada, C, C++ and Fortran)
34 and organized into subsystems and libraries, the GPRbuild
35 tool can be used. This tool, and the Project Manager
36 facility that it is based upon, is described in
37 *GPRbuild and GPR Companion Tools User's Guide*.
40 .. _The_GNAT_Make_Program_gnatmake:
42 Building with ``gnatmake``
43 ==========================
47 A typical development cycle when working on an Ada program consists of
50 #. Edit some sources to fix bugs;
54 #. Compile all sources affected;
56 #. Rebind and relink; and
60 .. index:: Dependency rules (compilation)
62 The third step in particular can be tricky, because not only do the modified
63 files have to be compiled, but any files depending on these files must also be
64 recompiled. The dependency rules in Ada can be quite complex, especially
65 in the presence of overloading, ``use`` clauses, generics and inlined
68 ``gnatmake`` automatically takes care of the third and fourth steps
69 of this process. It determines which sources need to be compiled,
70 compiles them, and binds and links the resulting object files.
72 Unlike some other Ada make programs, the dependencies are always
73 accurately recomputed from the new sources. The source based approach of
74 the GNAT compilation model makes this possible. This means that if
75 changes to the source program cause corresponding changes in
76 dependencies, they will always be tracked exactly correctly by
79 Note that for advanced forms of project structure, we recommend creating
80 a project file as explained in the *GNAT_Project_Manager* chapter in the
81 *GPRbuild User's Guide*, and using the
82 ``gprbuild`` tool which supports building with project files and works similarly
90 The usual form of the ``gnatmake`` command is
94 $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
96 The only required argument is one ``file_name``, which specifies
97 a compilation unit that is a main program. Several ``file_names`` can be
98 specified: this will result in several executables being built.
99 If ``switches`` are present, they can be placed before the first
100 ``file_name``, between ``file_names`` or after the last ``file_name``.
101 If ``mode_switches`` are present, they must always be placed after
102 the last ``file_name`` and all ``switches``.
104 If you are using standard file extensions (:file:`.adb` and
105 :file:`.ads`), then the
106 extension may be omitted from the ``file_name`` arguments. However, if
107 you are using non-standard extensions, then it is required that the
108 extension be given. A relative or absolute directory path can be
109 specified in a ``file_name``, in which case, the input source file will
110 be searched for in the specified directory only. Otherwise, the input
111 source file will first be searched in the directory where
112 ``gnatmake`` was invoked and if it is not found, it will be search on
113 the source path of the compiler as described in
114 :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
116 All ``gnatmake`` output (except when you specify :switch:`-M`) is sent to
117 :file:`stderr`. The output produced by the
118 :switch:`-M` switch is sent to :file:`stdout`.
121 .. _Switches_for_gnatmake:
123 Switches for ``gnatmake``
124 -------------------------
126 You may specify any of the following switches to ``gnatmake``:
129 .. index:: --version (gnatmake)
132 Display Copyright and version, then exit disregarding all other options.
135 .. index:: --help (gnatmake)
138 If ``--version`` was not used, display usage, then exit disregarding
142 .. index:: -P (gnatmake)
144 :switch:`-P{project}`
145 Build GNAT project file ``project`` using GPRbuild. When this switch is
146 present, all other command-line switches are treated as GPRbuild switches
147 and not ``gnatmake`` switches.
150 :ref:`gnatmake_and_Project_Files`.
153 .. index:: --GCC=compiler_name (gnatmake)
155 :switch:`--GCC={compiler_name}`
156 Program used for compiling. The default is ``gcc``. You need to use
157 quotes around ``compiler_name`` if ``compiler_name`` contains
158 spaces or other separator characters.
159 As an example ``--GCC="foo -x -y"``
160 will instruct ``gnatmake`` to use ``foo -x -y`` as your
161 compiler. A limitation of this syntax is that the name and path name of
162 the executable itself must not include any embedded spaces. Note that
163 switch :switch:`-c` is always inserted after your command name. Thus in the
164 above example the compiler command that will be used by ``gnatmake``
165 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
166 used, only the last ``compiler_name`` is taken into account. However,
167 all the additional switches are also taken into account. Thus,
168 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
169 ``--GCC="bar -x -y -z -t"``.
172 .. index:: --GNATBIND=binder_name (gnatmake)
174 :switch:`--GNATBIND={binder_name}`
175 Program used for binding. The default is ``gnatbind``. You need to
176 use quotes around ``binder_name`` if ``binder_name`` contains spaces
177 or other separator characters.
178 As an example ``--GNATBIND="bar -x -y"``
179 will instruct ``gnatmake`` to use ``bar -x -y`` as your
180 binder. Binder switches that are normally appended by ``gnatmake``
181 to ``gnatbind`` are now appended to the end of ``bar -x -y``.
182 A limitation of this syntax is that the name and path name of the executable
183 itself must not include any embedded spaces.
185 .. index:: --GNATLINK=linker_name (gnatmake)
187 :switch:`--GNATLINK={linker_name}`
188 Program used for linking. The default is ``gnatlink``. You need to
189 use quotes around ``linker_name`` if ``linker_name`` contains spaces
190 or other separator characters.
191 As an example ``--GNATLINK="lan -x -y"``
192 will instruct ``gnatmake`` to use ``lan -x -y`` as your
193 linker. Linker switches that are normally appended by ``gnatmake`` to
194 ``gnatlink`` are now appended to the end of ``lan -x -y``.
195 A limitation of this syntax is that the name and path name of the executable
196 itself must not include any embedded spaces.
198 :switch:`--create-map-file`
199 When linking an executable, create a map file. The name of the map file
200 has the same name as the executable with extension ".map".
202 :switch:`--create-map-file={mapfile}`
203 When linking an executable, create a map file with the specified name.
205 .. index:: --create-missing-dirs (gnatmake)
207 :switch:`--create-missing-dirs`
208 When using project files (:switch:`-P{project}`), automatically create
209 missing object directories, library directories and exec
212 :switch:`--single-compile-per-obj-dir`
213 Disallow simultaneous compilations in the same object directory when
214 project files are used.
216 :switch:`--subdirs={subdir}`
217 Actual object directory of each project file is the subdirectory subdir of the
218 object directory specified or defaulted in the project file.
220 :switch:`--unchecked-shared-lib-imports`
221 By default, shared library projects are not allowed to import static library
222 projects. When this switch is used on the command line, this restriction is
225 :switch:`--source-info={source info file}`
226 Specify a source info file. This switch is active only when project files
227 are used. If the source info file is specified as a relative path, then it is
228 relative to the object directory of the main project. If the source info file
229 does not exist, then after the Project Manager has successfully parsed and
230 processed the project files and found the sources, it creates the source info
231 file. If the source info file already exists and can be read successfully,
232 then the Project Manager will get all the needed information about the sources
233 from the source info file and will not look for them. This reduces the time
234 to process the project files, especially when looking for sources that take a
235 long time. If the source info file exists but cannot be parsed successfully,
236 the Project Manager will attempt to recreate it. If the Project Manager fails
237 to create the source info file, a message is issued, but gnatmake does not
238 fail. ``gnatmake`` "trusts" the source info file. This means that
239 if the source files have changed (addition, deletion, moving to a different
240 source directory), then the source info file need to be deleted and recreated.
243 .. index:: -a (gnatmake)
246 Consider all files in the make process, even the GNAT internal system
247 files (for example, the predefined Ada library files), as well as any
248 locked files. Locked files are files whose ALI file is write-protected.
250 ``gnatmake`` does not check these files,
251 because the assumption is that the GNAT internal files are properly up
252 to date, and also that any write protected ALI files have been properly
253 installed. Note that if there is an installation problem, such that one
254 of these files is not up to date, it will be properly caught by the
256 You may have to specify this switch if you are working on GNAT
257 itself. The switch ``-a`` is also useful
258 in conjunction with ``-f``
259 if you need to recompile an entire application,
260 including run-time files, using special configuration pragmas,
261 such as a ``Normalize_Scalars`` pragma.
264 ``gnatmake -a`` compiles all GNAT
266 ``gcc -c -gnatpg`` rather than ``gcc -c``.
269 .. index:: -b (gnatmake)
272 Bind only. Can be combined with :switch:`-c` to do
273 compilation and binding, but no link.
274 Can be combined with :switch:`-l`
275 to do binding and linking. When not combined with
277 all the units in the closure of the main program must have been previously
278 compiled and must be up to date. The root unit specified by ``file_name``
279 may be given without extension, with the source extension or, if no GNAT
280 Project File is specified, with the ALI file extension.
283 .. index:: -c (gnatmake)
286 Compile only. Do not perform binding, except when :switch:`-b`
287 is also specified. Do not perform linking, except if both
289 :switch:`-l` are also specified.
290 If the root unit specified by ``file_name`` is not a main unit, this is the
291 default. Otherwise ``gnatmake`` will attempt binding and linking
292 unless all objects are up to date and the executable is more recent than
296 .. index:: -C (gnatmake)
299 Use a temporary mapping file. A mapping file is a way to communicate
300 to the compiler two mappings: from unit names to file names (without
301 any directory information) and from file names to path names (with
302 full directory information). A mapping file can make the compiler's
303 file searches faster, especially if there are many source directories,
304 or the sources are read over a slow network connection. If
305 :switch:`-P` is used, a mapping file is always used, so
306 :switch:`-C` is unnecessary; in this case the mapping file
307 is initially populated based on the project file. If
308 :switch:`-C` is used without
310 the mapping file is initially empty. Each invocation of the compiler
311 will add any newly accessed sources to the mapping file.
314 .. index:: -C= (gnatmake)
317 Use a specific mapping file. The file, specified as a path name (absolute or
318 relative) by this switch, should already exist, otherwise the switch is
319 ineffective. The specified mapping file will be communicated to the compiler.
320 This switch is not compatible with a project file
321 (-P`file`) or with multiple compiling processes
322 (-jnnn, when nnn is greater than 1).
325 .. index:: -d (gnatmake)
328 Display progress for each source, up to date or not, as a single line:
332 completed x out of y (zz%)
334 If the file needs to be compiled this is displayed after the invocation of
335 the compiler. These lines are displayed even in quiet output mode.
338 .. index:: -D (gnatmake)
341 Put all object files and ALI file in directory ``dir``.
342 If the :switch:`-D` switch is not used, all object files
343 and ALI files go in the current working directory.
345 This switch cannot be used when using a project file.
348 .. index:: -eI (gnatmake)
351 Indicates that the main source is a multi-unit source and the rank of the unit
352 in the source file is nnn. nnn needs to be a positive number and a valid
353 index in the source. This switch cannot be used when ``gnatmake`` is
354 invoked for several mains.
357 .. index:: -eL (gnatmake)
358 .. index:: symbolic links
361 Follow all symbolic links when processing project files.
362 This should be used if your project uses symbolic links for files or
363 directories, but is not needed in other cases.
365 .. index:: naming scheme
367 This also assumes that no directory matches the naming scheme for files (for
368 instance that you do not have a directory called "sources.ads" when using the
369 default GNAT naming scheme).
371 When you do not have to use this switch (i.e., by default), gnatmake is able to
372 save a lot of system calls (several per source file and object file), which
373 can result in a significant speed up to load and manipulate a project file,
374 especially when using source files from a remote system.
377 .. index:: -eS (gnatmake)
380 Output the commands for the compiler, the binder and the linker
382 instead of standard error.
385 .. index:: -f (gnatmake)
388 Force recompilations. Recompile all sources, even though some object
389 files may be up to date, but don't recompile predefined or GNAT internal
390 files or locked files (files with a write-protected ALI file),
391 unless the :switch:`-a` switch is also specified.
394 .. index:: -F (gnatmake)
397 When using project files, if some errors or warnings are detected during
398 parsing and verbose mode is not in effect (no use of switch
399 -v), then error lines start with the full path name of the project
400 file, rather than its simple file name.
403 .. index:: -g (gnatmake)
406 Enable debugging. This switch is simply passed to the compiler and to the
410 .. index:: -i (gnatmake)
413 In normal mode, ``gnatmake`` compiles all object files and ALI files
414 into the current directory. If the :switch:`-i` switch is used,
415 then instead object files and ALI files that already exist are overwritten
416 in place. This means that once a large project is organized into separate
417 directories in the desired manner, then ``gnatmake`` will automatically
418 maintain and update this organization. If no ALI files are found on the
419 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
420 the new object and ALI files are created in the
421 directory containing the source being compiled. If another organization
422 is desired, where objects and sources are kept in different directories,
423 a useful technique is to create dummy ALI files in the desired directories.
424 When detecting such a dummy file, ``gnatmake`` will be forced to
425 recompile the corresponding source file, and it will be put the resulting
426 object and ALI files in the directory where it found the dummy file.
429 .. index:: -j (gnatmake)
430 .. index:: Parallel make
433 Use ``n`` processes to carry out the (re)compilations. On a multiprocessor
434 machine compilations will occur in parallel. If ``n`` is 0, then the
435 maximum number of parallel compilations is the number of core processors
436 on the platform. In the event of compilation errors, messages from various
437 compilations might get interspersed (but ``gnatmake`` will give you the
438 full ordered list of failing compiles at the end). If this is problematic,
439 rerun the make process with n set to 1 to get a clean list of messages.
442 .. index:: -k (gnatmake)
445 Keep going. Continue as much as possible after a compilation error. To
446 ease the programmer's task in case of compilation errors, the list of
447 sources for which the compile fails is given when ``gnatmake``
450 If ``gnatmake`` is invoked with several :file:`file_names` and with this
451 switch, if there are compilation errors when building an executable,
452 ``gnatmake`` will not attempt to build the following executables.
455 .. index:: -l (gnatmake)
458 Link only. Can be combined with :switch:`-b` to binding
459 and linking. Linking will not be performed if combined with
461 but not with :switch:`-b`.
462 When not combined with :switch:`-b`
463 all the units in the closure of the main program must have been previously
464 compiled and must be up to date, and the main program needs to have been bound.
465 The root unit specified by ``file_name``
466 may be given without extension, with the source extension or, if no GNAT
467 Project File is specified, with the ALI file extension.
470 .. index:: -m (gnatmake)
473 Specify that the minimum necessary amount of recompilations
474 be performed. In this mode ``gnatmake`` ignores time
475 stamp differences when the only
476 modifications to a source file consist in adding/removing comments,
477 empty lines, spaces or tabs. This means that if you have changed the
478 comments in a source file or have simply reformatted it, using this
479 switch will tell ``gnatmake`` not to recompile files that depend on it
480 (provided other sources on which these files depend have undergone no
481 semantic modifications). Note that the debugging information may be
482 out of date with respect to the sources if the :switch:`-m` switch causes
483 a compilation to be switched, so the use of this switch represents a
484 trade-off between compilation time and accurate debugging information.
487 .. index:: Dependencies, producing list
488 .. index:: -M (gnatmake)
491 Check if all objects are up to date. If they are, output the object
492 dependences to :file:`stdout` in a form that can be directly exploited in
493 a :file:`Makefile`. By default, each source file is prefixed with its
494 (relative or absolute) directory name. This name is whatever you
495 specified in the various :switch:`-aI`
496 and :switch:`-I` switches. If you use
497 ``gnatmake -M`` :switch:`-q`
498 (see below), only the source file names,
499 without relative paths, are output. If you just specify the :switch:`-M`
500 switch, dependencies of the GNAT internal system files are omitted. This
501 is typically what you want. If you also specify
502 the :switch:`-a` switch,
503 dependencies of the GNAT internal files are also listed. Note that
504 dependencies of the objects in external Ada libraries (see
505 switch :switch:`-aL{dir}` in the following list)
509 .. index:: -n (gnatmake)
512 Don't compile, bind, or link. Checks if all objects are up to date.
513 If they are not, the full name of the first file that needs to be
514 recompiled is printed.
515 Repeated use of this option, followed by compiling the indicated source
516 file, will eventually result in recompiling all required units.
519 .. index:: -o (gnatmake)
521 :switch:`-o {exec_name}`
522 Output executable name. The name of the final executable program will be
523 ``exec_name``. If the :switch:`-o` switch is omitted the default
524 name for the executable will be the name of the input file in appropriate form
525 for an executable file on the host system.
527 This switch cannot be used when invoking ``gnatmake`` with several
531 .. index:: -p (gnatmake)
534 Same as :switch:`--create-missing-dirs`
536 .. index:: -q (gnatmake)
539 Quiet. When this flag is not set, the commands carried out by
540 ``gnatmake`` are displayed.
543 .. index:: -s (gnatmake)
546 Recompile if compiler switches have changed since last compilation.
547 All compiler switches but -I and -o are taken into account in the
549 orders between different 'first letter' switches are ignored, but
550 orders between same switches are taken into account. For example,
551 :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O`
552 is equivalent to :switch:`-O -g`.
554 This switch is recommended when Integrated Preprocessing is used.
557 .. index:: -u (gnatmake)
560 Unique. Recompile at most the main files. It implies -c. Combined with
561 -f, it is equivalent to calling the compiler directly. Note that using
562 -u with a project file and no main has a special meaning.
565 (See :ref:`Project_Files_and_Main_Subprograms`.)
568 .. index:: -U (gnatmake)
571 When used without a project file or with one or several mains on the command
572 line, is equivalent to -u. When used with a project file and no main
573 on the command line, all sources of all project files are checked and compiled
574 if not up to date, and libraries are rebuilt, if necessary.
577 .. index:: -v (gnatmake)
580 Verbose. Display the reason for all recompilations ``gnatmake``
581 decides are necessary, with the highest verbosity level.
584 .. index:: -vl (gnatmake)
587 Verbosity level Low. Display fewer lines than in verbosity Medium.
590 .. index:: -vm (gnatmake)
593 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
596 .. index:: -vm (gnatmake)
599 Verbosity level High. Equivalent to -v.
603 Indicate the verbosity of the parsing of GNAT project files.
604 See :ref:`Switches_Related_to_Project_Files`.
607 .. index:: -x (gnatmake)
610 Indicate that sources that are not part of any Project File may be compiled.
611 Normally, when using Project Files, only sources that are part of a Project
612 File may be compile. When this switch is used, a source outside of all Project
613 Files may be compiled. The ALI file and the object file will be put in the
614 object directory of the main Project. The compilation switches used will only
615 be those specified on the command line. Even when
616 :switch:`-x` is used, mains specified on the
617 command line need to be sources of a project file.
620 :switch:`-X{name}={value}`
621 Indicate that external variable ``name`` has the value ``value``.
622 The Project Manager will use this value for occurrences of
623 ``external(name)`` when parsing the project file.
624 :ref:`Switches_Related_to_Project_Files`.
627 .. index:: -z (gnatmake)
630 No main subprogram. Bind and link the program even if the unit name
631 given on the command line is a package name. The resulting executable
632 will execute the elaboration routines of the package and its closure,
633 then the finalization routines.
636 .. rubric:: GCC switches
638 Any uppercase or multi-character switch that is not a ``gnatmake`` switch
639 is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
642 .. rubric:: Source and library search path switches
644 .. index:: -aI (gnatmake)
647 When looking for source files also look in directory ``dir``.
648 The order in which source files search is undertaken is
649 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
652 .. index:: -aL (gnatmake)
655 Consider ``dir`` as being an externally provided Ada library.
656 Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI`
657 files have been located in directory ``dir``. This allows you to have
658 missing bodies for the units in ``dir`` and to ignore out of date bodies
659 for the same units. You still need to specify
660 the location of the specs for these units by using the switches
661 :switch:`-aI{dir}` or :switch:`-I{dir}`.
662 Note: this switch is provided for compatibility with previous versions
663 of ``gnatmake``. The easier method of causing standard libraries
664 to be excluded from consideration is to write-protect the corresponding
668 .. index:: -aO (gnatmake)
671 When searching for library and object files, look in directory
672 ``dir``. The order in which library files are searched is described in
673 :ref:`Search_Paths_for_gnatbind`.
676 .. index:: Search paths, for gnatmake
677 .. index:: -A (gnatmake)
680 Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`.
683 .. index:: -I (gnatmake)
686 Equivalent to :switch:`-aO{dir} -aI{dir}`.
689 .. index:: -I- (gnatmake)
690 .. index:: Source files, suppressing search
693 Do not look for source files in the directory containing the source
694 file named in the command line.
695 Do not look for ALI or object files in the directory
696 where ``gnatmake`` was invoked.
699 .. index:: -L (gnatmake)
700 .. index:: Linker libraries
703 Add directory ``dir`` to the list of directories in which the linker
704 will search for libraries. This is equivalent to
705 :switch:`-largs` :switch:`-L{dir}`.
706 Furthermore, under Windows, the sources pointed to by the libraries path
707 set in the registry are not searched for.
710 .. index:: -nostdinc (gnatmake)
713 Do not look for source files in the system default directory.
716 .. index:: -nostdlib (gnatmake)
719 Do not look for library files in the system default directory.
722 .. index:: --RTS (gnatmake)
724 :switch:`--RTS={rts-path}`
725 Specifies the default location of the run-time library. GNAT looks for the
727 in the following directories, and stops as soon as a valid run-time is found
728 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
729 :file:`ada_object_path` present):
731 * *<current directory>/$rts_path*
733 * *<default-search-dir>/$rts_path*
735 * *<default-search-dir>/rts-$rts_path*
737 * The selected path is handled like a normal RTS path.
740 .. _Mode_Switches_for_gnatmake:
742 Mode Switches for ``gnatmake``
743 ------------------------------
745 The mode switches (referred to as ``mode_switches``) allow the
746 inclusion of switches that are to be passed to the compiler itself, the
747 binder or the linker. The effect of a mode switch is to cause all
748 subsequent switches up to the end of the switch list, or up to the next
749 mode switch, to be interpreted as switches to be passed on to the
750 designated component of GNAT.
752 .. index:: -cargs (gnatmake)
754 :switch:`-cargs {switches}`
755 Compiler switches. Here ``switches`` is a list of switches
756 that are valid switches for ``gcc``. They will be passed on to
757 all compile steps performed by ``gnatmake``.
760 .. index:: -bargs (gnatmake)
762 :switch:`-bargs {switches}`
763 Binder switches. Here ``switches`` is a list of switches
764 that are valid switches for ``gnatbind``. They will be passed on to
765 all bind steps performed by ``gnatmake``.
768 .. index:: -largs (gnatmake)
770 :switch:`-largs {switches}`
771 Linker switches. Here ``switches`` is a list of switches
772 that are valid switches for ``gnatlink``. They will be passed on to
773 all link steps performed by ``gnatmake``.
776 .. index:: -margs (gnatmake)
778 :switch:`-margs {switches}`
779 Make switches. The switches are directly interpreted by ``gnatmake``,
780 regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs`
784 .. _Notes_on_the_Command_Line:
786 Notes on the Command Line
787 -------------------------
789 This section contains some additional useful notes on the operation
790 of the ``gnatmake`` command.
792 .. index:: Recompilation (by gnatmake)
794 * If ``gnatmake`` finds no ALI files, it recompiles the main program
795 and all other units required by the main program.
796 This means that ``gnatmake``
797 can be used for the initial compile, as well as during subsequent steps of
798 the development cycle.
800 * If you enter ``gnatmake foo.adb``, where ``foo``
801 is a subunit or body of a generic unit, ``gnatmake`` recompiles
802 :file:`foo.adb` (because it finds no ALI) and stops, issuing a
805 * In ``gnatmake`` the switch :switch:`-I`
806 is used to specify both source and
807 library file paths. Use :switch:`-aI`
808 instead if you just want to specify
809 source paths only and :switch:`-aO`
810 if you want to specify library paths
813 * ``gnatmake`` will ignore any files whose ALI file is write-protected.
814 This may conveniently be used to exclude standard libraries from
815 consideration and in particular it means that the use of the
816 :switch:`-f` switch will not recompile these files
817 unless :switch:`-a` is also specified.
819 * ``gnatmake`` has been designed to make the use of Ada libraries
820 particularly convenient. Assume you have an Ada library organized
821 as follows: *obj-dir* contains the objects and ALI files for
822 of your Ada compilation units,
823 whereas *include-dir* contains the
824 specs of these units, but no bodies. Then to compile a unit
825 stored in ``main.adb``, which uses this Ada library you would just type:
829 $ gnatmake -aI`include-dir` -aL`obj-dir` main
831 * Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)`
832 switch provides a mechanism for avoiding unnecessary recompilations. Using
834 you can update the comments/format of your
835 source files without having to recompile everything. Note, however, that
836 adding or deleting lines in a source files may render its debugging
837 info obsolete. If the file in question is a spec, the impact is rather
838 limited, as that debugging info will only be useful during the
839 elaboration phase of your program. For bodies the impact can be more
840 significant. In all events, your debugger will warn you if a source file
841 is more recent than the corresponding object, and alert you to the fact
842 that the debugging information may be out of date.
845 .. _How_gnatmake_Works:
847 How ``gnatmake`` Works
848 ----------------------
850 Generally ``gnatmake`` automatically performs all necessary
851 recompilations and you don't need to worry about how it works. However,
852 it may be useful to have some basic understanding of the ``gnatmake``
853 approach and in particular to understand how it uses the results of
854 previous compilations without incorrectly depending on them.
856 First a definition: an object file is considered *up to date* if the
857 corresponding ALI file exists and if all the source files listed in the
858 dependency section of this ALI file have time stamps matching those in
859 the ALI file. This means that neither the source file itself nor any
860 files that it depends on have been modified, and hence there is no need
861 to recompile this file.
863 ``gnatmake`` works by first checking if the specified main unit is up
864 to date. If so, no compilations are required for the main unit. If not,
865 ``gnatmake`` compiles the main program to build a new ALI file that
866 reflects the latest sources. Then the ALI file of the main unit is
867 examined to find all the source files on which the main program depends,
868 and ``gnatmake`` recursively applies the above procedure on all these
871 This process ensures that ``gnatmake`` only trusts the dependencies
872 in an existing ALI file if they are known to be correct. Otherwise it
873 always recompiles to determine a new, guaranteed accurate set of
874 dependencies. As a result the program is compiled 'upside down' from what may
875 be more familiar as the required order of compilation in some other Ada
876 systems. In particular, clients are compiled before the units on which
877 they depend. The ability of GNAT to compile in any order is critical in
878 allowing an order of compilation to be chosen that guarantees that
879 ``gnatmake`` will recompute a correct set of new dependencies if
882 When invoking ``gnatmake`` with several ``file_names``, if a unit is
883 imported by several of the executables, it will be recompiled at most once.
885 Note: when using non-standard naming conventions
886 (:ref:`Using_Other_File_Names`), changing through a configuration pragmas
887 file the version of a source and invoking ``gnatmake`` to recompile may
888 have no effect, if the previous version of the source is still accessible
889 by ``gnatmake``. It may be necessary to use the switch
893 .. _Examples_of_gnatmake_Usage:
895 Examples of ``gnatmake`` Usage
896 ------------------------------
898 ``gnatmake hello.adb``
899 Compile all files necessary to bind and link the main program
900 :file:`hello.adb` (containing unit ``Hello``) and bind and link the
901 resulting object files to generate an executable file :file:`hello`.
903 ``gnatmake main1 main2 main3``
904 Compile all files necessary to bind and link the main programs
905 :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb`
906 (containing unit ``Main2``) and :file:`main3.adb`
907 (containing unit ``Main3``) and bind and link the resulting object files
908 to generate three executable files :file:`main1`,
909 :file:`main2` and :file:`main3`.
911 ``gnatmake -q Main_Unit -cargs -O2 -bargs -l``
912 Compile all files necessary to bind and link the main program unit
913 ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will
914 be done with optimization level 2 and the order of elaboration will be
915 listed by the binder. ``gnatmake`` will operate in quiet mode, not
916 displaying commands it is executing.
919 .. _Compiling_with_gcc:
921 Compiling with ``gcc``
922 ======================
924 This section discusses how to compile Ada programs using the ``gcc``
925 command. It also describes the set of switches
926 that can be used to control the behavior of the compiler.
928 .. _Compiling_Programs:
933 The first step in creating an executable program is to compile the units
934 of the program using the ``gcc`` command. You must compile the
937 * the body file (:file:`.adb`) for a library level subprogram or generic
940 * the spec file (:file:`.ads`) for a library level package or generic
941 package that has no body
943 * the body file (:file:`.adb`) for a library level package
944 or generic package that has a body
946 You need *not* compile the following files
948 * the spec of a library unit which has a body
952 because they are compiled as part of compiling related units. GNAT compiles
954 when the corresponding body is compiled, and subunits when the parent is
957 .. index:: cannot generate code
959 If you attempt to compile any of these files, you will get one of the
960 following error messages (where ``fff`` is the name of the file you
965 cannot generate code for file ``fff`` (package spec)
966 to check package spec, use -gnatc
968 cannot generate code for file ``fff`` (missing subunits)
969 to check parent unit, use -gnatc
971 cannot generate code for file ``fff`` (subprogram spec)
972 to check subprogram spec, use -gnatc
974 cannot generate code for file ``fff`` (subunit)
975 to check subunit, use -gnatc
978 As indicated by the above error messages, if you want to submit
979 one of these files to the compiler to check for correct semantics
980 without generating code, then use the :switch:`-gnatc` switch.
982 The basic command for compiling a file containing an Ada unit is:
986 $ gcc -c [switches] <file name>
988 where ``file name`` is the name of the Ada file (usually
989 having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
991 :switch:`-c` switch to tell ``gcc`` to compile, but not link, the file.
992 The result of a successful compilation is an object file, which has the
993 same name as the source file but an extension of :file:`.o` and an Ada
994 Library Information (ALI) file, which also has the same name as the
995 source file, but with :file:`.ali` as the extension. GNAT creates these
996 two output files in the current directory, but you may specify a source
997 file in any directory using an absolute or relative path specification
998 containing the directory information.
1002 ``gcc`` is actually a driver program that looks at the extensions of
1003 the file arguments and loads the appropriate compiler. For example, the
1004 GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`.
1005 These programs are in directories known to the driver program (in some
1006 configurations via environment variables you set), but need not be in
1007 your path. The ``gcc`` driver also calls the assembler and any other
1008 utilities needed to complete the generation of the required object
1011 It is possible to supply several file names on the same ``gcc``
1012 command. This causes ``gcc`` to call the appropriate compiler for
1013 each file. For example, the following command lists two separate
1014 files to be compiled:
1018 $ gcc -c x.adb y.adb
1021 calls ``gnat1`` (the Ada compiler) twice to compile :file:`x.adb` and
1023 The compiler generates two object files :file:`x.o` and :file:`y.o`
1024 and the two ALI files :file:`x.ali` and :file:`y.ali`.
1026 Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a
1027 list of available ``gcc`` switches.
1029 .. _Search_Paths_and_the_Run-Time_Library_RTL:
1031 Search Paths and the Run-Time Library (RTL)
1032 -------------------------------------------
1034 With the GNAT source-based library system, the compiler must be able to
1035 find source files for units that are needed by the unit being compiled.
1036 Search paths are used to guide this process.
1038 The compiler compiles one source file whose name must be given
1039 explicitly on the command line. In other words, no searching is done
1040 for this file. To find all other source files that are needed (the most
1041 common being the specs of units), the compiler examines the following
1042 directories, in the following order:
1044 * The directory containing the source file of the main unit being compiled
1045 (the file name on the command line).
1047 * Each directory named by an :switch:`-I` switch given on the ``gcc``
1048 command line, in the order given.
1050 .. index:: ADA_PRJ_INCLUDE_FILE
1052 * Each of the directories listed in the text file whose name is given
1053 by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable.
1054 :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat
1055 driver when project files are used. It should not normally be set
1058 .. index:: ADA_INCLUDE_PATH
1060 * Each of the directories listed in the value of the
1061 :envvar:`ADA_INCLUDE_PATH` environment variable.
1062 Construct this value
1063 exactly as the :envvar:`PATH` environment variable: a list of directory
1064 names separated by colons (semicolons when working with the NT version).
1066 * The content of the :file:`ada_source_path` file which is part of the GNAT
1067 installation tree and is used to store standard libraries such as the
1068 GNAT Run Time Library (RTL) source files.
1069 See also :ref:`Installing_a_library`.
1071 Specifying the switch :switch:`-I-`
1072 inhibits the use of the directory
1073 containing the source file named in the command line. You can still
1074 have this directory on your search path, but in this case it must be
1075 explicitly requested with a :switch:`-I` switch.
1077 Specifying the switch :switch:`-nostdinc`
1078 inhibits the search of the default location for the GNAT Run Time
1079 Library (RTL) source files.
1081 The compiler outputs its object files and ALI files in the current
1083 Caution: The object file can be redirected with the :switch:`-o` switch;
1084 however, ``gcc`` and ``gnat1`` have not been coordinated on this
1085 so the :file:`ALI` file will not go to the right place. Therefore, you should
1086 avoid using the :switch:`-o` switch.
1088 .. index:: System.IO
1090 The packages ``Ada``, ``System``, and ``Interfaces`` and their
1091 children make up the GNAT RTL, together with the simple ``System.IO``
1092 package used in the ``"Hello World"`` example. The sources for these units
1093 are needed by the compiler and are kept together in one directory. Not
1094 all of the bodies are needed, but all of the sources are kept together
1095 anyway. In a normal installation, you need not specify these directory
1096 names when compiling or binding. Either the environment variables or
1097 the built-in defaults cause these files to be found.
1099 In addition to the language-defined hierarchies (``System``, ``Ada`` and
1100 ``Interfaces``), the GNAT distribution provides a fourth hierarchy,
1101 consisting of child units of ``GNAT``. This is a collection of generally
1102 useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual`
1103 for further details.
1105 Besides simplifying access to the RTL, a major use of search paths is
1106 in compiling sources from multiple directories. This can make
1107 development environments much more flexible.
1109 .. _Order_of_Compilation_Issues:
1111 Order of Compilation Issues
1112 ---------------------------
1114 If, in our earlier example, there was a spec for the ``hello``
1115 procedure, it would be contained in the file :file:`hello.ads`; yet this
1116 file would not have to be explicitly compiled. This is the result of the
1117 model we chose to implement library management. Some of the consequences
1118 of this model are as follows:
1120 * There is no point in compiling specs (except for package
1121 specs with no bodies) because these are compiled as needed by clients. If
1122 you attempt a useless compilation, you will receive an error message.
1123 It is also useless to compile subunits because they are compiled as needed
1126 * There are no order of compilation requirements: performing a
1127 compilation never obsoletes anything. The only way you can obsolete
1128 something and require recompilations is to modify one of the
1129 source files on which it depends.
1131 * There is no library as such, apart from the ALI files
1132 (:ref:`The_Ada_Library_Information_Files`, for information on the format
1133 of these files). For now we find it convenient to create separate ALI files,
1134 but eventually the information therein may be incorporated into the object
1137 * When you compile a unit, the source files for the specs of all units
1138 that it |withs|, all its subunits, and the bodies of any generics it
1139 instantiates must be available (reachable by the search-paths mechanism
1140 described above), or you will receive a fatal error message.
1147 The following are some typical Ada compilation command line examples:
1153 Compile body in file :file:`xyz.adb` with all default options.
1157 $ gcc -c -O2 -gnata xyz-def.adb
1159 Compile the child unit package in file :file:`xyz-def.adb` with extensive
1160 optimizations, and pragma ``Assert``/``Debug`` statements
1165 $ gcc -c -gnatc abc-def.adb
1167 Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only
1171 .. _Switches_for_gcc:
1176 The ``gcc`` command accepts switches that control the
1177 compilation process. These switches are fully described in this section:
1178 first an alphabetical listing of all switches with a brief description,
1179 and then functionally grouped sets of switches with more detailed
1182 More switches exist for GCC than those documented here, especially
1183 for specific targets. However, their use is not recommended as
1184 they may change code generation in ways that are incompatible with
1185 the Ada run-time library, or can cause inconsistencies between
1188 .. _Alphabetical_List_of_All_Switches:
1190 Alphabetical List of All Switches
1191 ---------------------------------
1195 :switch:`-b {target}`
1196 Compile your program to run on ``target``, which is the name of a
1197 system configuration. You must have a GNAT cross-compiler built if
1198 ``target`` is not the same as your host system.
1204 Load compiler executables (for example, ``gnat1``, the Ada compiler)
1205 from ``dir`` instead of the default location. Only use this switch
1206 when multiple versions of the GNAT compiler are available.
1207 See the "Options for Directory Search" section in the
1208 :title:`Using the GNU Compiler Collection (GCC)` manual for further details.
1209 You would normally use the :switch:`-b` or :switch:`-V` switch instead.
1214 Compile. Always use this switch when compiling Ada programs.
1216 Note: for some other languages when using ``gcc``, notably in
1217 the case of C and C++, it is possible to use
1218 use ``gcc`` without a :switch:`-c` switch to
1219 compile and link in one step. In the case of GNAT, you
1220 cannot use this approach, because the binder must be run
1221 and ``gcc`` cannot be used to run the GNAT binder.
1224 .. index:: -fcallgraph-info (gcc)
1226 :switch:`-fcallgraph-info[=su,da]`
1227 Makes the compiler output callgraph information for the program, on a
1228 per-file basis. The information is generated in the VCG format. It can
1229 be decorated with additional, per-node and/or per-edge information, if a
1230 list of comma-separated markers is additionally specified. When the
1231 ``su`` marker is specified, the callgraph is decorated with stack usage
1232 information; it is equivalent to :switch:`-fstack-usage`. When the ``da``
1233 marker is specified, the callgraph is decorated with information about
1234 dynamically allocated objects.
1236 .. index:: -fdiagnostics-format (gcc)
1238 :switch:`-fdiagnostics-format=json`
1239 Makes GNAT emit warning and error messages as JSON. Inhibits printing of
1240 text warning and errors messages except if :switch:`-gnatv` or
1241 :switch:`-gnatl` are present. Uses absolute file paths when used along
1245 .. index:: -fdump-scos (gcc)
1247 :switch:`-fdump-scos`
1248 Generates SCO (Source Coverage Obligation) information in the ALI file.
1249 This information is used by advanced coverage tools. See unit :file:`SCOs`
1250 in the compiler sources for details in files :file:`scos.ads` and
1254 .. index:: -fgnat-encodings (gcc)
1256 :switch:`-fgnat-encodings=[all|gdb|minimal]`
1257 This switch controls the balance between GNAT encodings and standard DWARF
1258 emitted in the debug information.
1261 .. index:: -flto (gcc)
1263 :switch:`-flto[={n}]`
1264 Enables Link Time Optimization. This switch must be used in conjunction
1265 with the :switch:`-Ox` switches (but not with the :switch:`-gnatn` switch
1266 since it is a full replacement for the latter) and instructs the compiler
1267 to defer most optimizations until the link stage. The advantage of this
1268 approach is that the compiler can do a whole-program analysis and choose
1269 the best interprocedural optimization strategy based on a complete view
1270 of the program, instead of a fragmentary view with the usual approach.
1271 This can also speed up the compilation of big programs and reduce the
1272 size of the executable, compared with a traditional per-unit compilation
1273 with inlining across units enabled by the :switch:`-gnatn` switch.
1274 The drawback of this approach is that it may require more memory and that
1275 the debugging information generated by ``-g`` with it might be hardly usable.
1276 The switch, as well as the accompanying :switch:`-Ox` switches, must be
1277 specified both for the compilation and the link phases.
1278 If the ``n`` parameter is specified, the optimization and final code
1279 generation at link time are executed using ``n`` parallel jobs by
1280 means of an installed ``make`` program.
1283 .. index:: -fno-inline (gcc)
1285 :switch:`-fno-inline`
1286 Suppresses all inlining, unless requested with pragma ``Inline_Always``. The
1287 effect is enforced regardless of other optimization or inlining switches.
1288 Note that inlining can also be suppressed on a finer-grained basis with
1289 pragma ``No_Inline``.
1292 .. index:: -fno-inline-functions (gcc)
1294 :switch:`-fno-inline-functions`
1295 Suppresses automatic inlining of subprograms, which is enabled
1296 if :switch:`-O3` is used.
1299 .. index:: -fno-inline-small-functions (gcc)
1301 :switch:`-fno-inline-small-functions`
1302 Suppresses automatic inlining of small subprograms, which is enabled
1303 if :switch:`-O2` is used.
1306 .. index:: -fno-inline-functions-called-once (gcc)
1308 :switch:`-fno-inline-functions-called-once`
1309 Suppresses inlining of subprograms local to the unit and called once
1310 from within it, which is enabled if :switch:`-O1` is used.
1313 .. index:: -fno-ivopts (gcc)
1315 :switch:`-fno-ivopts`
1316 Suppresses high-level loop induction variable optimizations, which are
1317 enabled if :switch:`-O1` is used. These optimizations are generally
1318 profitable but, for some specific cases of loops with numerous uses
1319 of the iteration variable that follow a common pattern, they may end
1320 up destroying the regularity that could be exploited at a lower level
1321 and thus producing inferior code.
1324 .. index:: -fno-strict-aliasing (gcc)
1326 :switch:`-fno-strict-aliasing`
1327 Causes the compiler to avoid assumptions regarding non-aliasing
1328 of objects of different types. See
1329 :ref:`Optimization_and_Strict_Aliasing` for details.
1332 .. index:: -fno-strict-overflow (gcc)
1334 :switch:`-fno-strict-overflow`
1335 Causes the compiler to avoid assumptions regarding the rules of signed
1336 integer overflow. These rules specify that signed integer overflow will
1337 result in a Constraint_Error exception at run time and are enforced in
1338 default mode by the compiler, so this switch should not be necessary in
1339 normal operating mode. It might be useful in conjunction with :switch:`-gnato0`
1340 for very peculiar cases of low-level programming.
1343 .. index:: -fstack-check (gcc)
1345 :switch:`-fstack-check`
1346 Activates stack checking.
1347 See :ref:`Stack_Overflow_Checking` for details.
1350 .. index:: -fstack-usage (gcc)
1352 :switch:`-fstack-usage`
1353 Makes the compiler output stack usage information for the program, on a
1354 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
1360 Generate debugging information. This information is stored in the object
1361 file and copied from there to the final executable file by the linker,
1362 where it can be read by the debugger. You must use the
1363 :switch:`-g` switch if you plan on using the debugger.
1366 .. index:: -gnat05 (gcc)
1369 Allow full Ada 2005 features.
1372 .. index:: -gnat12 (gcc)
1375 Allow full Ada 2012 features.
1377 .. index:: -gnat83 (gcc)
1379 .. index:: -gnat2005 (gcc)
1382 Allow full Ada 2005 features (same as :switch:`-gnat05`)
1385 .. index:: -gnat2012 (gcc)
1388 Allow full Ada 2012 features (same as :switch:`-gnat12`)
1391 .. index:: -gnat2022 (gcc)
1394 Allow full Ada 2022 features
1398 Enforce Ada 83 restrictions.
1401 .. index:: -gnat95 (gcc)
1404 Enforce Ada 95 restrictions.
1406 Note: for compatibility with some Ada 95 compilers which support only
1407 the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can
1408 be used along with :switch:`-gnat95` to achieve a similar effect with GNAT.
1410 :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword
1411 and handle its associated semantic checks, even in Ada 95 mode.
1414 .. index:: -gnata (gcc)
1417 Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be
1418 activated. Note that these pragmas can also be controlled using the
1419 configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``.
1420 It also activates pragmas ``Check``, ``Precondition``, and
1421 ``Postcondition``. Note that these pragmas can also be controlled
1422 using the configuration pragma ``Check_Policy``. In Ada 2012, it
1423 also activates all assertions defined in the RM as aspects: preconditions,
1424 postconditions, type invariants and (sub)type predicates. In all Ada modes,
1425 corresponding pragmas for type invariants and (sub)type predicates are
1426 also activated. The default is that all these assertions are disabled,
1427 and have no effect, other than being checked for syntactic validity, and
1428 in the case of subtype predicates, constructions such as membership tests
1429 still test predicates even if assertions are turned off.
1432 .. index:: -gnatA (gcc)
1435 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
1439 .. index:: -gnatb (gcc)
1442 Generate brief messages to :file:`stderr` even if verbose mode set.
1445 .. index:: -gnatB (gcc)
1448 Assume no invalid (bad) values except for 'Valid attribute use
1449 (:ref:`Validity_Checking`).
1452 .. index:: -gnatc (gcc)
1455 Check syntax and semantics only (no code generation attempted). When the
1456 compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is
1457 only given to the compiler (after :switch:`-cargs` or in package Compiler of
1458 the project file), ``gnatmake`` will fail because it will not find the
1459 object file after compilation. If ``gnatmake`` is called with
1460 :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package
1461 Builder of the project file) then ``gnatmake`` will not fail because
1462 it will not look for the object files after compilation, and it will not try
1466 .. index:: -gnatC (gcc)
1469 Generate CodePeer intermediate format (no code generation attempted).
1470 This switch will generate an intermediate representation suitable for
1471 use by CodePeer (:file:`.scil` files). This switch is not compatible with
1472 code generation (it will, among other things, disable some switches such
1473 as ``-gnatn``, and enable others such as ``-gnata``).
1476 .. index:: -gnatd (gcc)
1479 Specify debug options for the compiler. The string of characters after
1480 the :switch:`-gnatd` specifies the specific debug options. The possible
1481 characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore.
1482 See compiler source file :file:`debug.adb` for details of the implemented
1483 debug options. Certain debug options are relevant to application
1484 programmers, and these are documented at appropriate points in this
1488 .. index:: -gnatD[nn] (gcc)
1491 Create expanded source files for source level debugging. This switch
1492 also suppresses generation of cross-reference information
1493 (see :switch:`-gnatx`). Note that this switch is not allowed if a previous
1494 ``-gnatR`` switch has been given, since these two switches are not compatible.
1497 .. index:: -gnateA (gcc)
1500 Check that the actual parameters of a subprogram call are not aliases of one
1501 another. To qualify as aliasing, their memory locations must be identical or
1502 overlapping, at least one of the corresponding formal parameters must be of
1503 mode OUT or IN OUT, and at least one of the corresponding formal parameters
1504 must have its parameter passing mechanism not specified.
1509 type Rec_Typ is record
1510 Data : Integer := 0;
1513 function Self (Val : Rec_Typ) return Rec_Typ is
1518 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
1521 end Detect_Aliasing;
1525 Detect_Aliasing (Obj, Obj);
1526 Detect_Aliasing (Obj, Self (Obj));
1529 In the example above, the first call to ``Detect_Aliasing`` fails with a
1530 ``Program_Error`` at run time because the actuals for ``Val_1`` and
1531 ``Val_2`` denote the same object. The second call executes without raising
1532 an exception because ``Self(Obj)`` produces an anonymous object which does
1533 not share the memory location of ``Obj``.
1535 .. index:: -gnateb (gcc)
1538 Store configuration files by their basename in ALI files. This switch is
1539 used for instance by gprbuild for distributed builds in order to prevent
1540 issues where machine-specific absolute paths could end up being stored in
1543 .. index:: -gnatec (gcc)
1545 :switch:`-gnatec={path}`
1546 Specify a configuration pragma file
1547 (the equal sign is optional)
1548 (:ref:`The_Configuration_Pragmas_Files`).
1551 .. index:: -gnateC (gcc)
1554 Generate CodePeer messages in a compiler-like format. This switch is only
1555 effective if :switch:`-gnatcC` is also specified and requires an installation
1559 .. index:: -gnated (gcc)
1562 Disable atomic synchronization
1565 .. index:: -gnateD (gcc)
1567 :switch:`-gnateDsymbol[={value}]`
1568 Defines a symbol, associated with ``value``, for preprocessing.
1569 (:ref:`Integrated_Preprocessing`).
1572 .. index:: -gnateE (gcc)
1575 Generate extra information in exception messages. In particular, display
1576 extra column information and the value and range associated with index and
1577 range check failures, and extra column information for access checks.
1578 In cases where the compiler is able to determine at compile time that
1579 a check will fail, it gives a warning, and the extra information is not
1580 produced at run time.
1583 .. index:: -gnatef (gcc)
1586 Display full source path name in brief error messages and absolute paths in
1587 :switch:`-fdiagnostics-format=json`'s output.
1590 .. index:: -gnateF (gcc)
1593 Check for overflow on all floating-point operations, including those
1594 for unconstrained predefined types. See description of pragma
1595 ``Check_Float_Overflow`` in GNAT RM.
1598 .. index:: -gnateg (gcc)
1603 The :switch:`-gnatc` switch must always be specified before this switch, e.g.
1604 :switch:`-gnatceg`. Generate a C header from the Ada input file. See
1605 :ref:`Generating_C_Headers_for_Ada_Specifications` for more
1609 .. index:: -gnateG (gcc)
1612 Save result of preprocessing in a text file.
1615 .. index:: -gnateH (gcc)
1618 Set the threshold from which the RM 13.5.1(13.3/2) clause applies to 64.
1619 This is useful only on 64-bit plaforms where this threshold is 128, but
1620 used to be 64 in earlier versions of the compiler.
1623 .. index:: -gnatei (gcc)
1625 :switch:`-gnatei{nnn}`
1626 Set maximum number of instantiations during compilation of a single unit to
1627 ``nnn``. This may be useful in increasing the default maximum of 8000 for
1628 the rare case when a single unit legitimately exceeds this limit.
1631 .. index:: -gnateI (gcc)
1633 :switch:`-gnateI{nnn}`
1634 Indicates that the source is a multi-unit source and that the index of the
1635 unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need
1636 to be a valid index in the multi-unit source.
1639 .. index:: -gnatel (gcc)
1642 This switch can be used with the static elaboration model to issue info
1644 where implicit ``pragma Elaborate`` and ``pragma Elaborate_All``
1645 are generated. This is useful in diagnosing elaboration circularities
1646 caused by these implicit pragmas when using the static elaboration
1647 model. See the section in this guide on elaboration checking for
1648 further details. These messages are not generated by default, and are
1649 intended only for temporary use when debugging circularity problems.
1652 .. index:: -gnatel (gcc)
1655 This switch turns off the info messages about implicit elaboration pragmas.
1658 .. index:: -gnatem (gcc)
1660 :switch:`-gnatem={path}`
1661 Specify a mapping file
1662 (the equal sign is optional)
1663 (:ref:`Units_to_Sources_Mapping_Files`).
1666 .. index:: -gnatep (gcc)
1668 :switch:`-gnatep={file}`
1669 Specify a preprocessing data file
1670 (the equal sign is optional)
1671 (:ref:`Integrated_Preprocessing`).
1674 .. index:: -gnateP (gcc)
1677 Turn categorization dependency errors into warnings.
1678 Ada requires that units that WITH one another have compatible categories, for
1679 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
1680 these errors become warnings (which can be ignored, or suppressed in the usual
1681 manner). This can be useful in some specialized circumstances such as the
1682 temporary use of special test software.
1685 .. index:: -gnateS (gcc)
1688 Synonym of :switch:`-fdump-scos`, kept for backwards compatibility.
1691 .. index:: -gnatet=file (gcc)
1693 :switch:`-gnatet={path}`
1694 Generate target dependent information. The format of the output file is
1695 described in the section about switch :switch:`-gnateT`.
1698 .. index:: -gnateT (gcc)
1700 :switch:`-gnateT={path}`
1701 Read target dependent information, such as endianness or sizes and alignments
1702 of base type. If this switch is passed, the default target dependent
1703 information of the compiler is replaced by the one read from the input file.
1704 This is used by tools other than the compiler, e.g. to do
1705 semantic analysis of programs that will run on some other target than
1706 the machine on which the tool is run.
1708 The following target dependent values should be defined,
1709 where ``Nat`` denotes a natural integer value, ``Pos`` denotes a
1710 positive integer value, and fields marked with a question mark are
1711 boolean fields, where a value of 0 is False, and a value of 1 is True:
1716 Bits_BE : Nat; -- Bits stored big-endian?
1717 Bits_Per_Unit : Pos; -- Bits in a storage unit
1718 Bits_Per_Word : Pos; -- Bits in a word
1719 Bytes_BE : Nat; -- Bytes stored big-endian?
1720 Char_Size : Pos; -- Standard.Character'Size
1721 Double_Float_Alignment : Nat; -- Alignment of double float
1722 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
1723 Double_Size : Pos; -- Standard.Long_Float'Size
1724 Float_Size : Pos; -- Standard.Float'Size
1725 Float_Words_BE : Nat; -- Float words stored big-endian?
1726 Int_Size : Pos; -- Standard.Integer'Size
1727 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
1728 Long_Long_Long_Size : Pos; -- Standard.Long_Long_Long_Integer'Size
1729 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
1730 Long_Size : Pos; -- Standard.Long_Integer'Size
1731 Maximum_Alignment : Pos; -- Maximum permitted alignment
1732 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
1733 Pointer_Size : Pos; -- System.Address'Size
1734 Short_Enums : Nat; -- Foreign enums use short size?
1735 Short_Size : Pos; -- Standard.Short_Integer'Size
1736 Strict_Alignment : Nat; -- Strict alignment?
1737 System_Allocator_Alignment : Nat; -- Alignment for malloc calls
1738 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
1739 Words_BE : Nat; -- Words stored big-endian?
1741 ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of
1742 GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be
1743 the number of bits in an addressable storage unit (byte); normally 8.`
1745 ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of
1746 GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word;
1749 ``Double_Float_Alignment``, if not zero, is the maximum alignment that the
1750 compiler can choose by default for a 64-bit floating-point type or object.
1752 ``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
1753 compiler can choose by default for a 64-bit or larger scalar type or object.
1755 ``Maximum_Alignment`` is the maximum alignment that the compiler can choose
1756 by default for a type or object, which is also the maximum alignment that can
1757 be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT
1758 / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
1759 follows: `Biggest alignment that any data type can require on this machine,
1762 ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
1763 64 for the majority of GCC targets (but can be different on some targets).
1765 ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
1766 documented as follows: `Define this macro to be the value 1 if instructions
1767 will fail to work if given data not on the nominal alignment. If instructions
1768 will merely go slower in that case, define this macro as 0.`
1770 ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
1771 by calls to ``malloc``.
1774 The format of the input file is as follows. First come the values of
1775 the variables defined above, with one line per value:
1782 where ``name`` is the name of the parameter, spelled out in full,
1783 and cased as in the above list, and ``value`` is an unsigned decimal
1784 integer. Two or more blanks separates the name from the value.
1786 All the variables must be present, in alphabetical order (i.e. the
1787 same order as the list above).
1789 Then there is a blank line to separate the two parts of the file. Then
1790 come the lines showing the floating-point types to be registered, with
1791 one line per registered mode:
1796 name digs float_rep size alignment
1799 where ``name`` is the string name of the type (which can have
1800 single spaces embedded in the name, e.g. long double), ``digs`` is
1801 the number of digits for the floating-point type, ``float_rep`` is
1802 the float representation (I for IEEE-754-Binary, which is
1803 the only one supported at this time),
1804 ``size`` is the size in bits, ``alignment`` is the
1805 alignment in bits. The name is followed by at least two blanks, fields
1806 are separated by at least one blank, and a LF character immediately
1807 follows the alignment field.
1809 Here is an example of a target parameterization file:
1819 Double_Float_Alignment 0
1820 Double_Scalar_Alignment 0
1825 Long_Double_Size 128
1826 Long_Long_Long_Size 128
1829 Maximum_Alignment 16
1830 Max_Unaligned_Field 64
1834 System_Allocator_Alignment 16
1840 long double 18 I 80 128
1845 .. index:: -gnateu (gcc)
1848 Ignore unrecognized validity, warning, and style switches that
1849 appear after this switch is given. This may be useful when
1850 compiling sources developed on a later version of the compiler
1851 with an earlier version. Of course the earlier version must
1852 support this switch.
1855 .. index:: -gnateV (gcc)
1858 Check that all actual parameters of a subprogram call are valid according to
1859 the rules of validity checking (:ref:`Validity_Checking`).
1862 .. index:: -gnateY (gcc)
1865 Ignore all STYLE_CHECKS pragmas. Full legality checks
1866 are still carried out, but the pragmas have no effect
1867 on what style checks are active. This allows all style
1868 checking options to be controlled from the command line.
1871 .. index:: -gnatE (gcc)
1874 Dynamic elaboration checking mode enabled. For further details see
1875 :ref:`Elaboration_Order_Handling_in_GNAT`.
1878 .. index:: -gnatf (gcc)
1881 Full errors. Multiple errors per line, all undefined references, do not
1882 attempt to suppress cascaded errors.
1885 .. index:: -gnatF (gcc)
1888 Externals names are folded to all uppercase.
1891 .. index:: -gnatg (gcc)
1894 Internal GNAT implementation mode. This should not be used for applications
1895 programs, it is intended only for use by the compiler and its run-time
1896 library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
1897 implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
1898 warnings and all standard style options are turned on. All warnings and style
1899 messages are treated as errors.
1902 .. index:: -gnatG[nn] (gcc)
1905 List generated expanded code in source form.
1908 .. index:: -gnath (gcc)
1911 Output usage information. The output is written to :file:`stdout`.
1914 .. index:: -gnatH (gcc)
1917 Legacy elaboration-checking mode enabled. When this switch is in effect,
1918 the pre-18.x access-before-elaboration model becomes the de facto model.
1919 For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1922 .. index:: -gnati (gcc)
1925 Identifier character set (``c`` = 1/2/3/4/5/9/p/8/f/n/w).
1926 For details of the possible selections for ``c``,
1927 see :ref:`Character_Set_Control`.
1930 .. index:: -gnatI (gcc)
1933 Ignore representation clauses. When this switch is used,
1934 representation clauses are treated as comments. This is useful
1935 when initially porting code where you want to ignore rep clause
1936 problems, and also for compiling foreign code (particularly
1937 for use with ASIS). The representation clauses that are ignored
1938 are: enumeration_representation_clause, record_representation_clause,
1939 and attribute_definition_clause for the following attributes:
1940 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1941 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
1942 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
1943 Note that this option should be used only for compiling -- the
1944 code is likely to malfunction at run time.
1947 .. index:: -gnatjnn (gcc)
1949 :switch:`-gnatj{nn}`
1950 Reformat error messages to fit on ``nn`` character lines
1953 .. index:: -gnatJ (gcc)
1956 Permissive elaboration-checking mode enabled. When this switch is in effect,
1957 the post-18.x access-before-elaboration model ignores potential issues with:
1960 - Activations of tasks defined in instances
1962 - Calls from within an instance to its enclosing context
1963 - Calls through generic formal parameters
1964 - Calls to subprograms defined in instances
1966 - Indirect calls using 'Access
1967 - Requeue statements
1969 - Synchronous task suspension
1971 and does not emit compile-time diagnostics or run-time checks. For further
1972 details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1975 .. index:: -gnatk (gcc)
1977 :switch:`-gnatk={n}`
1978 Limit file names to ``n`` (1-999) characters (``k`` = krunch).
1981 .. index:: -gnatl (gcc)
1984 Output full source listing with embedded error messages.
1987 .. index:: -gnatL (gcc)
1990 Used in conjunction with -gnatG or -gnatD to intersperse original
1991 source lines (as comment lines with line numbers) in the expanded
1995 .. index:: -gnatm (gcc)
1997 :switch:`-gnatm={n}`
1998 Limit number of detected error or warning messages to ``n``
1999 where ``n`` is in the range 1..999999. The default setting if
2000 no switch is given is 9999. If the number of warnings reaches this
2001 limit, then a message is output and further warnings are suppressed,
2002 but the compilation is continued. If the number of error messages
2003 reaches this limit, then a message is output and the compilation
2004 is abandoned. The equal sign here is optional. A value of zero
2005 means that no limit applies.
2008 .. index:: -gnatn (gcc)
2010 :switch:`-gnatn[12]`
2011 Activate inlining across units for subprograms for which pragma ``Inline``
2012 is specified. This inlining is performed by the GCC back-end. An optional
2013 digit sets the inlining level: 1 for moderate inlining across units
2014 or 2 for full inlining across units. If no inlining level is specified,
2015 the compiler will pick it based on the optimization level.
2018 .. index:: -gnatN (gcc)
2021 Activate front end inlining for subprograms for which
2022 pragma ``Inline`` is specified. This inlining is performed
2023 by the front end and will be visible in the
2024 :switch:`-gnatG` output.
2026 When using a gcc-based back end, then the use of
2027 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
2028 Historically front end inlining was more extensive than the gcc back end
2029 inlining, but that is no longer the case.
2032 .. index:: -gnato0 (gcc)
2035 Suppresses overflow checking. This causes the behavior of the compiler to
2036 match the default for older versions where overflow checking was suppressed
2037 by default. This is equivalent to having
2038 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
2041 .. index:: -gnato?? (gcc)
2044 Set default mode for handling generation of code to avoid intermediate
2045 arithmetic overflow. Here ``??`` is two digits, a
2046 single digit, or nothing. Each digit is one of the digits ``1``
2049 ===== ===============================================================
2050 Digit Interpretation
2051 ----- ---------------------------------------------------------------
2052 *1* All intermediate overflows checked against base type (``STRICT``)
2053 *2* Minimize intermediate overflows (``MINIMIZED``)
2054 *3* Eliminate intermediate overflows (``ELIMINATED``)
2055 ===== ===============================================================
2057 If only one digit appears, then it applies to all
2058 cases; if two digits are given, then the first applies outside
2059 assertions, pre/postconditions, and type invariants, and the second
2060 applies within assertions, pre/postconditions, and type invariants.
2062 If no digits follow the :switch:`-gnato`, then it is equivalent to
2064 causing all intermediate overflows to be handled in strict
2067 This switch also causes arithmetic overflow checking to be performed
2068 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
2070 The default if no option :switch:`-gnato` is given is that overflow handling
2071 is in ``STRICT`` mode (computations done using the base type), and that
2072 overflow checking is enabled.
2074 Note that division by zero is a separate check that is not
2075 controlled by this switch (divide-by-zero checking is on by default).
2077 See also :ref:`Specifying_the_Desired_Mode`.
2080 .. index:: -gnatp (gcc)
2083 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
2084 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
2087 .. index:: -gnat-p (gcc)
2090 Cancel effect of previous :switch:`-gnatp` switch.
2093 .. index:: -gnatq (gcc)
2096 Don't quit. Try semantics, even if parse errors.
2099 .. index:: -gnatQ (gcc)
2102 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2103 Note that code generation is still suppressed in the presence of any
2104 errors, so even with :switch:`-gnatQ` no object file is generated.
2107 .. index:: -gnatr (gcc)
2110 Treat pragma Restrictions as Restriction_Warnings.
2113 .. index:: -gnatR (gcc)
2115 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
2116 Output representation information for declared types, objects and
2117 subprograms. Note that this switch is not allowed if a previous
2118 :switch:`-gnatD` switch has been given, since these two switches
2122 .. index:: -gnats (gcc)
2128 .. index:: -gnatS (gcc)
2131 Print package Standard.
2134 .. index:: -gnatT (gcc)
2136 :switch:`-gnatT{nnn}`
2137 All compiler tables start at ``nnn`` times usual starting size.
2140 .. index:: -gnatu (gcc)
2143 List units for this compilation.
2146 .. index:: -gnatU (gcc)
2149 Tag all error messages with the unique string 'error:'
2152 .. index:: -gnatv (gcc)
2155 Verbose mode. Full error output with source lines to :file:`stdout`.
2158 .. index:: -gnatV (gcc)
2161 Control level of validity checking (:ref:`Validity_Checking`).
2164 .. index:: -gnatw (gcc)
2166 :switch:`-gnatw{xxx}`
2168 ``xxx`` is a string of option letters that denotes
2169 the exact warnings that
2170 are enabled or disabled (:ref:`Warning_Message_Control`).
2173 .. index:: -gnatW (gcc)
2176 Wide character encoding method
2177 (``e``\ =n/h/u/s/e/8).
2180 .. index:: -gnatx (gcc)
2183 Suppress generation of cross-reference information.
2186 .. index:: -gnatX (gcc)
2189 Enable core GNAT implementation extensions and latest Ada version.
2192 .. index:: -gnatX0 (gcc)
2195 Enable all GNAT implementation extensions and latest Ada version.
2198 .. index:: -gnaty (gcc)
2201 Enable built-in style checks (:ref:`Style_Checking`).
2204 .. index:: -gnatz (gcc)
2207 Distribution stub generation and compilation
2208 (``m``\ =r/c for receiver/caller stubs).
2216 Direct GNAT to search the ``dir`` directory for source files needed by
2217 the current compilation
2218 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2221 .. index:: -I- (gcc)
2226 Except for the source file named in the command line, do not look for source
2227 files in the directory containing the source file named in the command line
2228 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2234 This switch is used in ``gcc`` to redirect the generated object file
2235 and its associated ALI file. Beware of this switch with GNAT, because it may
2236 cause the object file and ALI file to have different names which in turn
2237 may confuse the binder and the linker.
2240 .. index:: -nostdinc (gcc)
2243 Inhibit the search of the default location for the GNAT Run Time
2244 Library (RTL) source files.
2247 .. index:: -nostdlib (gcc)
2250 Inhibit the search of the default location for the GNAT Run Time
2251 Library (RTL) ALI files.
2257 ``n`` controls the optimization level:
2259 ======= ==================================================================
2261 ------- ------------------------------------------------------------------
2262 *0* No optimization, the default setting if no :switch:`-O` appears
2263 *1* Normal optimization, the default if you specify :switch:`-O` without an
2264 operand. A good compromise between code quality and compilation
2266 *2* Extensive optimization, may improve execution time, possibly at
2267 the cost of substantially increased compilation time.
2268 *3* Same as :switch:`-O2`, and also includes inline expansion for small
2269 subprograms in the same unit.
2270 *s* Optimize space usage
2271 ======= ==================================================================
2273 See also :ref:`Optimization_Levels`.
2276 .. index:: -pass-exit-codes (gcc)
2278 :switch:`-pass-exit-codes`
2279 Catch exit codes from the compiler and use the most meaningful as
2283 .. index:: --RTS (gcc)
2285 :switch:`--RTS={rts-path}`
2286 Specifies the default location of the run-time library. Same meaning as the
2287 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
2293 Used in place of :switch:`-c` to
2294 cause the assembler source file to be
2295 generated, using :file:`.s` as the extension,
2296 instead of the object file.
2297 This may be useful if you need to examine the generated assembly code.
2300 .. index:: -fverbose-asm (gcc)
2302 :switch:`-fverbose-asm`
2303 Used in conjunction with :switch:`-S`
2304 to cause the generated assembly code file to be annotated with variable
2305 names, making it significantly easier to follow.
2311 Show commands generated by the ``gcc`` driver. Normally used only for
2312 debugging purposes or if you need to be sure what version of the
2313 compiler you are executing.
2319 Execute ``ver`` version of the compiler. This is the ``gcc``
2320 version, not the GNAT version.
2326 Turn off warnings generated by the back end of the compiler. Use of
2327 this switch also causes the default for front end warnings to be set
2328 to suppress (as though :switch:`-gnatws` had appeared at the start of
2332 .. index:: Combining GNAT switches
2334 You may combine a sequence of GNAT switches into a single switch. For
2335 example, the combined switch
2341 is equivalent to specifying the following sequence of switches:
2345 -gnato -gnatf -gnati3
2347 The following restrictions apply to the combination of switches
2350 * The switch :switch:`-gnatc` if combined with other switches must come
2351 first in the string.
2353 * The switch :switch:`-gnats` if combined with other switches must come
2354 first in the string.
2357 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
2358 switches, and only one of them may appear in the command line.
2360 * The switch :switch:`-gnat-p` may not be combined with any other switch.
2362 * Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
2363 switch), then all further characters in the switch are interpreted
2364 as style modifiers (see description of :switch:`-gnaty`).
2366 * Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
2367 switch), then all further characters in the switch are interpreted
2368 as debug flags (see description of :switch:`-gnatd`).
2370 * Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
2371 switch), then all further characters in the switch are interpreted
2372 as warning mode modifiers (see description of :switch:`-gnatw`).
2374 * Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
2375 switch), then all further characters in the switch are interpreted
2376 as validity checking options (:ref:`Validity_Checking`).
2378 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2379 a combined list of options.
2381 .. _Output_and_Error_Message_Control:
2383 Output and Error Message Control
2384 --------------------------------
2388 The standard default format for error messages is called 'brief format'.
2389 Brief format messages are written to :file:`stderr` (the standard error
2390 file) and have the following form:
2394 e.adb:3:04: Incorrect spelling of keyword "function"
2395 e.adb:4:20: ";" should be "is"
2397 The first integer after the file name is the line number in the file,
2398 and the second integer is the column number within the line.
2399 ``GNAT Studio`` can parse the error messages
2400 and point to the referenced character.
2401 The following switches provide control over the error message
2405 .. index:: -gnatv (gcc)
2408 The ``v`` stands for verbose.
2409 The effect of this setting is to write long-format error
2410 messages to :file:`stdout` (the standard output file).
2411 The same program compiled with the
2412 :switch:`-gnatv` switch would generate:
2416 3. funcion X (Q : Integer)
2418 >>> Incorrect spelling of keyword "function"
2421 >>> ";" should be "is"
2424 The vertical bar indicates the location of the error, and the ``>>>``
2425 prefix can be used to search for error messages. When this switch is
2426 used the only source lines output are those with errors.
2429 .. index:: -gnatl (gcc)
2432 The ``l`` stands for list.
2433 This switch causes a full listing of
2434 the file to be generated. In the case where a body is
2435 compiled, the corresponding spec is also listed, along
2436 with any subunits. Typical output from compiling a package
2437 body :file:`p.adb` might look like::
2441 1. package body p is
2443 3. procedure a is separate;
2454 2. pragma Elaborate_Body
2475 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
2476 standard output is redirected, a brief summary is written to
2477 :file:`stderr` (standard error) giving the number of error messages and
2478 warning messages generated.
2481 .. index:: -gnatl=fname (gcc)
2483 :switch:`-gnatl={fname}`
2484 This has the same effect as :switch:`-gnatl` except that the output is
2485 written to a file instead of to standard output. If the given name
2486 :file:`fname` does not start with a period, then it is the full name
2487 of the file to be written. If :file:`fname` is an extension, it is
2488 appended to the name of the file being compiled. For example, if
2489 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
2490 then the output is written to file xyz.adb.lst.
2493 .. index:: -gnatU (gcc)
2496 This switch forces all error messages to be preceded by the unique
2497 string 'error:'. This means that error messages take a few more
2498 characters in space, but allows easy searching for and identification
2502 .. index:: -gnatb (gcc)
2505 The ``b`` stands for brief.
2506 This switch causes GNAT to generate the
2507 brief format error messages to :file:`stderr` (the standard error
2508 file) as well as the verbose
2509 format message or full listing (which as usual is written to
2510 :file:`stdout`, the standard output file).
2513 .. index:: -gnatm (gcc)
2515 :switch:`-gnatm={n}`
2516 The ``m`` stands for maximum.
2517 ``n`` is a decimal integer in the
2518 range of 1 to 999999 and limits the number of error or warning
2519 messages to be generated. For example, using
2520 :switch:`-gnatm2` might yield
2524 e.adb:3:04: Incorrect spelling of keyword "function"
2525 e.adb:5:35: missing ".."
2526 fatal error: maximum number of errors detected
2527 compilation abandoned
2530 The default setting if
2531 no switch is given is 9999. If the number of warnings reaches this
2532 limit, then a message is output and further warnings are suppressed,
2533 but the compilation is continued. If the number of error messages
2534 reaches this limit, then a message is output and the compilation
2535 is abandoned. A value of zero means that no limit applies.
2537 Note that the equal sign is optional, so the switches
2538 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
2541 .. index:: -gnatf (gcc)
2544 .. index:: Error messages, suppressing
2546 The ``f`` stands for full.
2547 Normally, the compiler suppresses error messages that are likely to be
2548 redundant. This switch causes all error
2549 messages to be generated. In particular, in the case of
2550 references to undefined variables. If a given variable is referenced
2551 several times, the normal format of messages is
2555 e.adb:7:07: "V" is undefined (more references follow)
2557 where the parenthetical comment warns that there are additional
2558 references to the variable ``V``. Compiling the same program with the
2559 :switch:`-gnatf` switch yields
2563 e.adb:7:07: "V" is undefined
2564 e.adb:8:07: "V" is undefined
2565 e.adb:8:12: "V" is undefined
2566 e.adb:8:16: "V" is undefined
2567 e.adb:9:07: "V" is undefined
2568 e.adb:9:12: "V" is undefined
2570 The :switch:`-gnatf` switch also generates additional information for
2571 some error messages. Some examples are:
2573 * Details on possibly non-portable unchecked conversion
2575 * List possible interpretations for ambiguous calls
2577 * Additional details on incorrect parameters
2580 .. index:: -gnatjnn (gcc)
2583 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
2584 with continuation lines are treated as though the continuation lines were
2585 separate messages (and so a warning with two continuation lines counts as
2586 three warnings, and is listed as three separate messages).
2588 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
2589 messages are output in a different manner. A message and all its continuation
2590 lines are treated as a unit, and count as only one warning or message in the
2591 statistics totals. Furthermore, the message is reformatted so that no line
2592 is longer than nn characters.
2595 .. index:: -gnatq (gcc)
2598 The ``q`` stands for quit (really 'don't quit').
2599 In normal operation mode, the compiler first parses the program and
2600 determines if there are any syntax errors. If there are, appropriate
2601 error messages are generated and compilation is immediately terminated.
2603 GNAT to continue with semantic analysis even if syntax errors have been
2604 found. This may enable the detection of more errors in a single run. On
2605 the other hand, the semantic analyzer is more likely to encounter some
2606 internal fatal error when given a syntactically invalid tree.
2609 .. index:: -gnatQ (gcc)
2612 In normal operation mode, the :file:`ALI` file is not generated if any
2613 illegalities are detected in the program. The use of :switch:`-gnatQ` forces
2614 generation of the :file:`ALI` file. This file is marked as being in
2615 error, so it cannot be used for binding purposes, but it does contain
2616 reasonably complete cross-reference information, and thus may be useful
2617 for use by tools (e.g., semantic browsing tools or integrated development
2618 environments) that are driven from the :file:`ALI` file. This switch
2619 implies :switch:`-gnatq`, since the semantic phase must be run to get a
2620 meaningful ALI file.
2622 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
2623 being in error, ``gnatmake`` will attempt to recompile the source when it
2624 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
2626 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
2627 since ALI files are never generated if :switch:`-gnats` is set.
2630 .. _Warning_Message_Control:
2632 Warning Message Control
2633 -----------------------
2635 .. index:: Warning messages
2637 In addition to error messages, which correspond to illegalities as defined
2638 in the Ada Reference Manual, the compiler detects two kinds of warning
2641 First, the compiler considers some constructs suspicious and generates a
2642 warning message to alert you to a possible error. Second, if the
2643 compiler detects a situation that is sure to raise an exception at
2644 run time, it generates a warning message. The following shows an example
2645 of warning messages:
2649 e.adb:4:24: warning: creation of object may raise Storage_Error
2650 e.adb:10:17: warning: static value out of range
2651 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2654 GNAT considers a large number of situations as appropriate
2655 for the generation of warning messages. As always, warnings are not
2656 definite indications of errors. For example, if you do an out-of-range
2657 assignment with the deliberate intention of raising a
2658 ``Constraint_Error`` exception, then the warning that may be
2659 issued does not indicate an error. Some of the situations for which GNAT
2660 issues warnings (at least some of the time) are given in the following
2661 list. This list is not complete, and new warnings are often added to
2662 subsequent versions of GNAT. The list is intended to give a general idea
2663 of the kinds of warnings that are generated.
2665 * Possible infinitely recursive calls
2667 * Out-of-range values being assigned
2669 * Possible order of elaboration problems
2671 * Size not a multiple of alignment for a record type
2673 * Assertions (pragma Assert) that are sure to fail
2677 * Address clauses with possibly unaligned values, or where an attempt is
2678 made to overlay a smaller variable with a larger one.
2680 * Fixed-point type declarations with a null range
2682 * Direct_IO or Sequential_IO instantiated with a type that has access values
2684 * Variables that are never assigned a value
2686 * Variables that are referenced before being initialized
2688 * Task entries with no corresponding ``accept`` statement
2690 * Duplicate accepts for the same task entry in a ``select``
2692 * Objects that take too much storage
2694 * Unchecked conversion between types of differing sizes
2696 * Missing ``return`` statement along some execution path in a function
2698 * Incorrect (unrecognized) pragmas
2700 * Incorrect external names
2702 * Allocation from empty storage pool
2704 * Potentially blocking operation in protected type
2706 * Suspicious parenthesization of expressions
2708 * Mismatching bounds in an aggregate
2710 * Attempt to return local value by reference
2712 * Premature instantiation of a generic body
2714 * Attempt to pack aliased components
2716 * Out of bounds array subscripts
2718 * Wrong length on string assignment
2720 * Violations of style rules if style checking is enabled
2722 * Unused |with| clauses
2724 * ``Bit_Order`` usage that does not have any effect
2726 * ``Standard.Duration`` used to resolve universal fixed expression
2728 * Dereference of possibly null value
2730 * Declaration that is likely to cause storage error
2732 * Internal GNAT unit |withed| by application unit
2734 * Values known to be out of range at compile time
2736 * Unreferenced or unmodified variables. Note that a special
2737 exemption applies to variables which contain any of the substrings
2738 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
2739 are considered likely to be intentionally used in a situation where
2740 otherwise a warning would be given, so warnings of this kind are
2741 always suppressed for such variables.
2743 * Address overlays that could clobber memory
2745 * Unexpected initialization when address clause present
2747 * Bad alignment for address clause
2749 * Useless type conversions
2751 * Redundant assignment statements and other redundant constructs
2753 * Useless exception handlers
2755 * Accidental hiding of name by child unit
2757 * Access before elaboration detected at compile time
2759 * A range in a ``for`` loop that is known to be null or might be null
2762 The following section lists compiler switches that are available
2763 to control the handling of warning messages. It is also possible
2764 to exercise much finer control over what warnings are issued and
2765 suppressed using the GNAT pragma Warnings (see the description
2766 of the pragma in the :title:`GNAT_Reference_manual`).
2769 .. index:: -gnatwa (gcc)
2772 *Activate most optional warnings.*
2774 This switch activates most optional warning messages. See the remaining list
2775 in this section for details on optional warning messages that can be
2776 individually controlled. The warnings that are not turned on by this
2780 * :switch:`-gnatwd` (implicit dereferencing)
2782 * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
2784 * :switch:`-gnatwh` (hiding)
2786 * :switch:`-gnatw.h` (holes in record layouts)
2788 * :switch:`-gnatw.j` (late primitives of tagged types)
2790 * :switch:`-gnatw.k` (redefinition of names in standard)
2792 * :switch:`-gnatwl` (elaboration warnings)
2794 * :switch:`-gnatw.l` (inherited aspects)
2796 * :switch:`-gnatw.n` (atomic synchronization)
2798 * :switch:`-gnatwo` (address clause overlay)
2800 * :switch:`-gnatw.o` (values set by out parameters ignored)
2802 * :switch:`-gnatw.q` (questionable layout of record types)
2804 * :switch:`-gnatw_q` (ignored equality)
2806 * :switch:`-gnatw_r` (out-of-order record representation clauses)
2808 * :switch:`-gnatw.s` (overridden size clause)
2810 * :switch:`-gnatw_s` (ineffective predicate test)
2812 * :switch:`-gnatwt` (tracking of deleted conditional code)
2814 * :switch:`-gnatw.u` (unordered enumeration)
2816 * :switch:`-gnatw.w` (use of Warnings Off)
2818 * :switch:`-gnatw.y` (reasons for package needing body)
2820 All other optional warnings are turned on.
2823 .. index:: -gnatwA (gcc)
2826 *Suppress all optional errors.*
2828 This switch suppresses all optional warning messages, see remaining list
2829 in this section for details on optional warning messages that can be
2830 individually controlled. Note that unlike switch :switch:`-gnatws`, the
2831 use of switch :switch:`-gnatwA` does not suppress warnings that are
2832 normally given unconditionally and cannot be individually controlled
2833 (for example, the warning about a missing exit path in a function).
2834 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
2835 the use of switch :switch:`-gnatwA` can be individually turned back
2836 on. For example the use of switch :switch:`-gnatwA` followed by
2837 switch :switch:`-gnatwd` will suppress all optional warnings except
2838 the warnings for implicit dereferencing.
2840 .. index:: -gnatw.a (gcc)
2843 *Activate warnings on failing assertions.*
2845 .. index:: Assert failures
2847 This switch activates warnings for assertions where the compiler can tell at
2848 compile time that the assertion will fail. Note that this warning is given
2849 even if assertions are disabled. The default is that such warnings are
2853 .. index:: -gnatw.A (gcc)
2856 *Suppress warnings on failing assertions.*
2858 .. index:: Assert failures
2860 This switch suppresses warnings for assertions where the compiler can tell at
2861 compile time that the assertion will fail.
2867 *Activate warnings on anonymous allocators.*
2869 .. index:: Anonymous allocators
2871 This switch activates warnings for allocators of anonymous access types,
2872 which can involve run-time accessibility checks and lead to unexpected
2873 accessibility violations. For more details on the rules involved, see
2880 *Suppress warnings on anonymous allocators.*
2882 .. index:: Anonymous allocators
2884 This switch suppresses warnings for anonymous access type allocators.
2887 .. index:: -gnatwb (gcc)
2890 *Activate warnings on bad fixed values.*
2892 .. index:: Bad fixed values
2894 .. index:: Fixed-point Small value
2896 .. index:: Small value
2898 This switch activates warnings for static fixed-point expressions whose
2899 value is not an exact multiple of Small. Such values are implementation
2900 dependent, since an implementation is free to choose either of the multiples
2901 that surround the value. GNAT always chooses the closer one, but this is not
2902 required behavior, and it is better to specify a value that is an exact
2903 multiple, ensuring predictable execution. The default is that such warnings
2907 .. index:: -gnatwB (gcc)
2910 *Suppress warnings on bad fixed values.*
2912 This switch suppresses warnings for static fixed-point expressions whose
2913 value is not an exact multiple of Small.
2916 .. index:: -gnatw.b (gcc)
2919 *Activate warnings on biased representation.*
2921 .. index:: Biased representation
2923 This switch activates warnings when a size clause, value size clause, component
2924 clause, or component size clause forces the use of biased representation for an
2925 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2926 to represent 10/11). The default is that such warnings are generated.
2929 .. index:: -gnatwB (gcc)
2932 *Suppress warnings on biased representation.*
2934 This switch suppresses warnings for representation clauses that force the use
2935 of biased representation.
2938 .. index:: -gnatwc (gcc)
2941 *Activate warnings on conditionals.*
2943 .. index:: Conditionals, constant
2945 This switch activates warnings for conditional expressions used in
2946 tests that are known to be True or False at compile time. The default
2947 is that such warnings are not generated.
2948 Note that this warning does
2949 not get issued for the use of boolean constants whose
2950 values are known at compile time, since this is a standard technique
2951 for conditional compilation in Ada, and this would generate too many
2952 false positive warnings.
2954 This warning option also activates a special test for comparisons using
2955 the operators '>=' and' <='.
2956 If the compiler can tell that only the equality condition is possible,
2957 then it will warn that the '>' or '<' part of the test
2958 is useless and that the operator could be replaced by '='.
2959 An example would be comparing a ``Natural`` variable <= 0.
2961 This warning option also generates warnings if
2962 one or both tests is optimized away in a membership test for integer
2963 values if the result can be determined at compile time. Range tests on
2964 enumeration types are not included, since it is common for such tests
2965 to include an end point.
2967 This warning can also be turned on using :switch:`-gnatwa`.
2970 .. index:: -gnatwC (gcc)
2973 *Suppress warnings on conditionals.*
2975 This switch suppresses warnings for conditional expressions used in
2976 tests that are known to be True or False at compile time.
2979 .. index:: -gnatw.c (gcc)
2982 *Activate warnings on missing component clauses.*
2984 .. index:: Component clause, missing
2986 This switch activates warnings for record components where a record
2987 representation clause is present and has component clauses for the
2988 majority, but not all, of the components. A warning is given for each
2989 component for which no component clause is present.
2992 .. index:: -gnatw.C (gcc)
2995 *Suppress warnings on missing component clauses.*
2997 This switch suppresses warnings for record components that are
2998 missing a component clause in the situation described above.
3001 .. index:: -gnatw_c (gcc)
3004 *Activate warnings on unknown condition in Compile_Time_Warning.*
3006 .. index:: Compile_Time_Warning
3007 .. index:: Compile_Time_Error
3009 This switch activates warnings on a pragma Compile_Time_Warning
3010 or Compile_Time_Error whose condition has a value that is not
3011 known at compile time.
3012 The default is that such warnings are generated.
3015 .. index:: -gnatw_C (gcc)
3018 *Suppress warnings on unknown condition in Compile_Time_Warning.*
3020 This switch suppresses warnings on a pragma Compile_Time_Warning
3021 or Compile_Time_Error whose condition has a value that is not
3022 known at compile time.
3025 .. index:: -gnatwd (gcc)
3028 *Activate warnings on implicit dereferencing.*
3030 If this switch is set, then the use of a prefix of an access type
3031 in an indexed component, slice, or selected component without an
3032 explicit ``.all`` will generate a warning. With this warning
3033 enabled, access checks occur only at points where an explicit
3034 ``.all`` appears in the source code (assuming no warnings are
3035 generated as a result of this switch). The default is that such
3036 warnings are not generated.
3039 .. index:: -gnatwD (gcc)
3042 *Suppress warnings on implicit dereferencing.*
3044 .. index:: Implicit dereferencing
3046 .. index:: Dereferencing, implicit
3048 This switch suppresses warnings for implicit dereferences in
3049 indexed components, slices, and selected components.
3052 .. index:: -gnatw.d (gcc)
3055 *Activate tagging of warning and info messages.*
3057 If this switch is set, then warning messages are tagged, with one of the
3061 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
3066 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
3071 Used to tag elaboration information (info) messages generated when the
3072 static model of elaboration is used and the :switch:`-gnatel` switch is set.
3075 - *[restriction warning]*
3076 Used to tag warning messages for restriction violations, activated by use
3077 of the pragma ``Restriction_Warnings``.
3080 - *[warning-as-error]*
3081 Used to tag warning messages that have been converted to error messages by
3082 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
3083 the string "error: " rather than "warning: ".
3086 - *[enabled by default]*
3087 Used to tag all other warnings that are always given by default, unless
3088 warnings are completely suppressed using pragma *Warnings(Off)* or
3089 the switch :switch:`-gnatws`.
3093 .. index:: -gnatw.d (gcc)
3096 *Deactivate tagging of warning and info messages messages.*
3098 If this switch is set, then warning messages return to the default
3099 mode in which warnings and info messages are not tagged as described above for
3103 .. index:: -gnatwe (gcc)
3104 .. index:: Warnings, treat as error
3107 *Treat warnings and style checks as errors.*
3109 This switch causes warning messages and style check messages to be
3111 The warning string still appears, but the warning messages are counted
3112 as errors, and prevent the generation of an object file. Note that this
3113 is the only -gnatw switch that affects the handling of style check messages.
3114 Note also that this switch has no effect on info (information) messages, which
3115 are not treated as errors if this switch is present.
3118 .. index:: -gnatw.e (gcc)
3121 *Activate every optional warning.*
3123 .. index:: Warnings, activate every optional warning
3125 This switch activates all optional warnings, including those which
3126 are not activated by :switch:`-gnatwa`. The use of this switch is not
3127 recommended for normal use. If you turn this switch on, it is almost
3128 certain that you will get large numbers of useless warnings. The
3129 warnings that are excluded from :switch:`-gnatwa` are typically highly
3130 specialized warnings that are suitable for use only in code that has
3131 been specifically designed according to specialized coding rules.
3134 .. index:: -gnatwE (gcc)
3135 .. index:: Warnings, treat as error
3138 *Treat all run-time exception warnings as errors.*
3140 This switch causes warning messages regarding errors that will be raised
3141 during run-time execution to be treated as errors.
3144 .. index:: -gnatwf (gcc)
3147 *Activate warnings on unreferenced formals.*
3149 .. index:: Formals, unreferenced
3151 This switch causes a warning to be generated if a formal parameter
3152 is not referenced in the body of the subprogram. This warning can
3153 also be turned on using :switch:`-gnatwu`. The
3154 default is that these warnings are not generated.
3157 .. index:: -gnatwF (gcc)
3160 *Suppress warnings on unreferenced formals.*
3162 This switch suppresses warnings for unreferenced formal
3163 parameters. Note that the
3164 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
3165 effect of warning on unreferenced entities other than subprogram
3169 .. index:: -gnatwg (gcc)
3172 *Activate warnings on unrecognized pragmas.*
3174 .. index:: Pragmas, unrecognized
3176 This switch causes a warning to be generated if an unrecognized
3177 pragma is encountered. Apart from issuing this warning, the
3178 pragma is ignored and has no effect. The default
3179 is that such warnings are issued (satisfying the Ada Reference
3180 Manual requirement that such warnings appear).
3183 .. index:: -gnatwG (gcc)
3186 *Suppress warnings on unrecognized pragmas.*
3188 This switch suppresses warnings for unrecognized pragmas.
3191 .. index:: -gnatw.g (gcc)
3194 *Warnings used for GNAT sources.*
3196 This switch sets the warning categories that are used by the standard
3197 GNAT style. Currently this is equivalent to
3198 :switch:`-gnatwAao.q.s.CI.V.X.Z`
3199 but more warnings may be added in the future without advanced notice.
3202 .. index:: -gnatwh (gcc)
3205 *Activate warnings on hiding.*
3207 .. index:: Hiding of Declarations
3209 This switch activates warnings on hiding declarations that are considered
3210 potentially confusing. Not all cases of hiding cause warnings; for example an
3211 overriding declaration hides an implicit declaration, which is just normal
3212 code. The default is that warnings on hiding are not generated.
3215 .. index:: -gnatwH (gcc)
3218 *Suppress warnings on hiding.*
3220 This switch suppresses warnings on hiding declarations.
3223 .. index:: -gnatw.h (gcc)
3226 *Activate warnings on holes/gaps in records.*
3228 .. index:: Record Representation (gaps)
3230 This switch activates warnings on component clauses in record
3231 representation clauses that leave holes (gaps) in the record layout.
3232 If a record representation clause does not specify a location for
3233 every component of the record type, then the warnings generated (or not
3234 generated) are unspecified. For example, there may be gaps for which
3235 either no warning is generated or a warning is generated that
3236 incorrectly describes the location of the gap. This undesirable situation
3237 can sometimes be avoided by adding (and specifying the location for) unused
3241 .. index:: -gnatw.H (gcc)
3244 *Suppress warnings on holes/gaps in records.*
3246 This switch suppresses warnings on component clauses in record
3247 representation clauses that leave holes (haps) in the record layout.
3250 .. index:: -gnatwi (gcc)
3253 *Activate warnings on implementation units.*
3255 This switch activates warnings for a |with| of an internal GNAT
3256 implementation unit, defined as any unit from the ``Ada``,
3257 ``Interfaces``, ``GNAT``,
3259 hierarchies that is not
3260 documented in either the Ada Reference Manual or the GNAT
3261 Programmer's Reference Manual. Such units are intended only
3262 for internal implementation purposes and should not be |withed|
3263 by user programs. The default is that such warnings are generated
3266 .. index:: -gnatwI (gcc)
3269 *Disable warnings on implementation units.*
3271 This switch disables warnings for a |with| of an internal GNAT
3272 implementation unit.
3275 .. index:: -gnatw.i (gcc)
3278 *Activate warnings on overlapping actuals.*
3280 This switch enables a warning on statically detectable overlapping actuals in
3281 a subprogram call, when one of the actuals is an in-out parameter, and the
3282 types of the actuals are not by-copy types. This warning is off by default.
3285 .. index:: -gnatw.I (gcc)
3288 *Disable warnings on overlapping actuals.*
3290 This switch disables warnings on overlapping actuals in a call.
3293 .. index:: -gnatwj (gcc)
3296 *Activate warnings on obsolescent features (Annex J).*
3298 .. index:: Features, obsolescent
3300 .. index:: Obsolescent features
3302 If this warning option is activated, then warnings are generated for
3303 calls to subprograms marked with ``pragma Obsolescent`` and
3304 for use of features in Annex J of the Ada Reference Manual. In the
3305 case of Annex J, not all features are flagged. In particular, uses of package
3306 ``ASCII`` are not flagged, since these are very common and
3307 would generate many annoying positive warnings. The default is that
3308 such warnings are not generated.
3310 In addition to the above cases, warnings are also generated for
3311 GNAT features that have been provided in past versions but which
3312 have been superseded (typically by features in the new Ada standard).
3313 For example, ``pragma Ravenscar`` will be flagged since its
3314 function is replaced by ``pragma Profile(Ravenscar)``, and
3315 ``pragma Interface_Name`` will be flagged since its function
3316 is replaced by ``pragma Import``.
3318 Note that this warning option functions differently from the
3319 restriction ``No_Obsolescent_Features`` in two respects.
3320 First, the restriction applies only to annex J features.
3321 Second, the restriction does flag uses of package ``ASCII``.
3324 .. index:: -gnatwJ (gcc)
3327 *Suppress warnings on obsolescent features (Annex J).*
3329 This switch disables warnings on use of obsolescent features.
3332 .. index:: -gnatw.j (gcc)
3335 *Activate warnings on late declarations of tagged type primitives.*
3337 This switch activates warnings on visible primitives added to a
3338 tagged type after deriving a private extension from it.
3341 .. index:: -gnatw.J (gcc)
3344 *Suppress warnings on late declarations of tagged type primitives.*
3346 This switch suppresses warnings on visible primitives added to a
3347 tagged type after deriving a private extension from it.
3350 .. index:: -gnatwk (gcc)
3353 *Activate warnings on variables that could be constants.*
3355 This switch activates warnings for variables that are initialized but
3356 never modified, and then could be declared constants. The default is that
3357 such warnings are not given.
3360 .. index:: -gnatwK (gcc)
3363 *Suppress warnings on variables that could be constants.*
3365 This switch disables warnings on variables that could be declared constants.
3368 .. index:: -gnatw.k (gcc)
3371 *Activate warnings on redefinition of names in standard.*
3373 This switch activates warnings for declarations that declare a name that
3374 is defined in package Standard. Such declarations can be confusing,
3375 especially since the names in package Standard continue to be directly
3376 visible, meaning that use visibility on such redeclared names does not
3377 work as expected. Names of discriminants and components in records are
3378 not included in this check.
3381 .. index:: -gnatwK (gcc)
3384 *Suppress warnings on redefinition of names in standard.*
3386 This switch disables warnings for declarations that declare a name that
3387 is defined in package Standard.
3390 .. index:: -gnatwl (gcc)
3393 *Activate warnings for elaboration pragmas.*
3395 .. index:: Elaboration, warnings
3397 This switch activates warnings for possible elaboration problems,
3398 including suspicious use
3399 of ``Elaborate`` pragmas, when using the static elaboration model, and
3400 possible situations that may raise ``Program_Error`` when using the
3401 dynamic elaboration model.
3402 See the section in this guide on elaboration checking for further details.
3403 The default is that such warnings
3407 .. index:: -gnatwL (gcc)
3410 *Suppress warnings for elaboration pragmas.*
3412 This switch suppresses warnings for possible elaboration problems.
3415 .. index:: -gnatw.l (gcc)
3418 *List inherited aspects.*
3420 This switch causes the compiler to list inherited invariants,
3421 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3422 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3425 .. index:: -gnatw.L (gcc)
3428 *Suppress listing of inherited aspects.*
3430 This switch suppresses listing of inherited aspects.
3433 .. index:: -gnatwm (gcc)
3436 *Activate warnings on modified but unreferenced variables.*
3438 This switch activates warnings for variables that are assigned (using
3439 an initialization value or with one or more assignment statements) but
3440 whose value is never read. The warning is suppressed for volatile
3441 variables and also for variables that are renamings of other variables
3442 or for which an address clause is given.
3443 The default is that these warnings are not given.
3446 .. index:: -gnatwM (gcc)
3449 *Disable warnings on modified but unreferenced variables.*
3451 This switch disables warnings for variables that are assigned or
3452 initialized, but never read.
3455 .. index:: -gnatw.m (gcc)
3458 *Activate warnings on suspicious modulus values.*
3460 This switch activates warnings for modulus values that seem suspicious.
3461 The cases caught are where the size is the same as the modulus (e.g.
3462 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3463 with no size clause. The guess in both cases is that 2**x was intended
3464 rather than x. In addition expressions of the form 2*x for small x
3465 generate a warning (the almost certainly accurate guess being that
3466 2**x was intended). This switch also activates warnings for negative
3467 literal values of a modular type, which are interpreted as large positive
3468 integers after wrap-around. The default is that these warnings are given.
3472 .. index:: -gnatw.M (gcc)
3475 *Disable warnings on suspicious modulus values.*
3477 This switch disables warnings for suspicious modulus values.
3480 .. index:: -gnatwn (gcc)
3483 *Set normal warnings mode.*
3485 This switch sets normal warning mode, in which enabled warnings are
3486 issued and treated as warnings rather than errors. This is the default
3487 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
3488 an explicit :switch:`-gnatws` or
3489 :switch:`-gnatwe`. It also cancels the effect of the
3490 implicit :switch:`-gnatwe` that is activated by the
3491 use of :switch:`-gnatg`.
3494 .. index:: -gnatw.n (gcc)
3495 .. index:: Atomic Synchronization, warnings
3498 *Activate warnings on atomic synchronization.*
3500 This switch actives warnings when an access to an atomic variable
3501 requires the generation of atomic synchronization code. These
3502 warnings are off by default.
3504 .. index:: -gnatw.N (gcc)
3507 *Suppress warnings on atomic synchronization.*
3509 .. index:: Atomic Synchronization, warnings
3511 This switch suppresses warnings when an access to an atomic variable
3512 requires the generation of atomic synchronization code.
3515 .. index:: -gnatwo (gcc)
3516 .. index:: Address Clauses, warnings
3519 *Activate warnings on address clause overlays.*
3521 This switch activates warnings for possibly unintended initialization
3522 effects of defining address clauses that cause one variable to overlap
3523 another. The default is that such warnings are generated.
3526 .. index:: -gnatwO (gcc)
3529 *Suppress warnings on address clause overlays.*
3531 This switch suppresses warnings on possibly unintended initialization
3532 effects of defining address clauses that cause one variable to overlap
3536 .. index:: -gnatw.o (gcc)
3539 *Activate warnings on modified but unreferenced out parameters.*
3541 This switch activates warnings for variables that are modified by using
3542 them as actuals for a call to a procedure with an out mode formal, where
3543 the resulting assigned value is never read. It is applicable in the case
3544 where there is more than one out mode formal. If there is only one out
3545 mode formal, the warning is issued by default (controlled by -gnatwu).
3546 The warning is suppressed for volatile
3547 variables and also for variables that are renamings of other variables
3548 or for which an address clause is given.
3549 The default is that these warnings are not given.
3552 .. index:: -gnatw.O (gcc)
3555 *Disable warnings on modified but unreferenced out parameters.*
3557 This switch suppresses warnings for variables that are modified by using
3558 them as actuals for a call to a procedure with an out mode formal, where
3559 the resulting assigned value is never read.
3562 .. index:: -gnatwp (gcc)
3563 .. index:: Inlining, warnings
3566 *Activate warnings on ineffective pragma Inlines.*
3568 This switch activates warnings for failure of front end inlining
3569 (activated by :switch:`-gnatN`) to inline a particular call. There are
3570 many reasons for not being able to inline a call, including most
3571 commonly that the call is too complex to inline. The default is
3572 that such warnings are not given.
3573 Warnings on ineffective inlining by the gcc back-end can be activated
3574 separately, using the gcc switch -Winline.
3577 .. index:: -gnatwP (gcc)
3580 *Suppress warnings on ineffective pragma Inlines.*
3582 This switch suppresses warnings on ineffective pragma Inlines. If the
3583 inlining mechanism cannot inline a call, it will simply ignore the
3587 .. index:: -gnatw.p (gcc)
3588 .. index:: Parameter order, warnings
3591 *Activate warnings on parameter ordering.*
3593 This switch activates warnings for cases of suspicious parameter
3594 ordering when the list of arguments are all simple identifiers that
3595 match the names of the formals, but are in a different order. The
3596 warning is suppressed if any use of named parameter notation is used,
3597 so this is the appropriate way to suppress a false positive (and
3598 serves to emphasize that the "misordering" is deliberate). The
3599 default is that such warnings are not given.
3602 .. index:: -gnatw.P (gcc)
3605 *Suppress warnings on parameter ordering.*
3607 This switch suppresses warnings on cases of suspicious parameter
3611 .. index:: -gnatw_p (gcc)
3614 *Activate warnings for pedantic checks.*
3616 This switch activates warnings for the failure of certain pedantic checks.
3617 The only case currently supported is a check that the subtype_marks given
3618 for corresponding formal parameter and function results in a subprogram
3619 declaration and its body denote the same subtype declaration. The default
3620 is that such warnings are not given.
3622 .. index:: -gnatw_P (gcc)
3625 *Suppress warnings for pedantic checks.*
3627 This switch suppresses warnings on violations of pedantic checks.
3630 .. index:: -gnatwq (gcc)
3631 .. index:: Parentheses, warnings
3634 *Activate warnings on questionable missing parentheses.*
3636 This switch activates warnings for cases where parentheses are not used and
3637 the result is potential ambiguity from a readers point of view. For example
3638 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3639 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3640 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3641 follow the rule of always parenthesizing to make the association clear, and
3642 this warning switch warns if such parentheses are not present. The default
3643 is that these warnings are given.
3646 .. index:: -gnatwQ (gcc)
3649 *Suppress warnings on questionable missing parentheses.*
3651 This switch suppresses warnings for cases where the association is not
3652 clear and the use of parentheses is preferred.
3655 .. index:: -gnatw.q (gcc)
3656 .. index:: Layout, warnings
3659 *Activate warnings on questionable layout of record types.*
3661 This switch activates warnings for cases where the default layout of
3662 a record type, that is to say the layout of its components in textual
3663 order of the source code, would very likely cause inefficiencies in
3664 the code generated by the compiler, both in terms of space and speed
3665 during execution. One warning is issued for each problematic component
3666 without representation clause in the nonvariant part and then in each
3667 variant recursively, if any.
3669 The purpose of these warnings is neither to prescribe an optimal layout
3670 nor to force the use of representation clauses, but rather to get rid of
3671 the most blatant inefficiencies in the layout. Therefore, the default
3672 layout is matched against the following synthetic ordered layout and
3673 the deviations are flagged on a component-by-component basis:
3675 * first all components or groups of components whose length is fixed
3676 and a multiple of the storage unit,
3678 * then the remaining components whose length is fixed and not a multiple
3679 of the storage unit,
3681 * then the remaining components whose length doesn't depend on discriminants
3682 (that is to say, with variable but uniform length for all objects),
3684 * then all components whose length depends on discriminants,
3686 * finally the variant part (if any),
3688 for the nonvariant part and for each variant recursively, if any.
3690 The exact wording of the warning depends on whether the compiler is allowed
3691 to reorder the components in the record type or precluded from doing it by
3692 means of pragma ``No_Component_Reordering``.
3694 The default is that these warnings are not given.
3696 .. index:: -gnatw.Q (gcc)
3699 *Suppress warnings on questionable layout of record types.*
3701 This switch suppresses warnings for cases where the default layout of
3702 a record type would very likely cause inefficiencies.
3705 .. index:: -gnatw_q (gcc)
3708 *Activate warnings for ignored equality operators.*
3710 This switch activates warnings for a user-defined "=" function that does
3711 not compose (i.e. is ignored for a predefined "=" for a composite type
3712 containing a component whose type has the user-defined "=" as
3713 primitive). Note that the user-defined "=" must be a primitive operator
3714 in order to trigger the warning.
3715 See RM-4.5.2(14/3-15/5, 21, 24/3, 32.1/1)
3716 for the exact Ada rules on composability of "=".
3718 The default is that these warnings are not given.
3720 .. index:: -gnatw_Q (gcc)
3723 *Suppress warnings for ignored equality operators.*
3726 .. index:: -gnatwr (gcc)
3729 *Activate warnings on redundant constructs.*
3731 This switch activates warnings for redundant constructs. The following
3732 is the current list of constructs regarded as redundant:
3734 * Assignment of an item to itself.
3736 * Type conversion that converts an expression to its own type.
3738 * Use of the attribute ``Base`` where ``typ'Base`` is the same
3741 * Use of pragma ``Pack`` when all components are placed by a record
3742 representation clause.
3744 * Exception handler containing only a reraise statement (raise with no
3745 operand) which has no effect.
3747 * Use of the operator abs on an operand that is known at compile time
3750 * Comparison of an object or (unary or binary) operation of boolean type to
3751 an explicit True value.
3753 * Import of parent package.
3755 The default is that warnings for redundant constructs are not given.
3758 .. index:: -gnatwR (gcc)
3761 *Suppress warnings on redundant constructs.*
3763 This switch suppresses warnings for redundant constructs.
3766 .. index:: -gnatw.r (gcc)
3769 *Activate warnings for object renaming function.*
3771 This switch activates warnings for an object renaming that renames a
3772 function call, which is equivalent to a constant declaration (as
3773 opposed to renaming the function itself). The default is that these
3777 .. index:: -gnatw.R (gcc)
3780 *Suppress warnings for object renaming function.*
3782 This switch suppresses warnings for object renaming function.
3785 .. index:: -gnatw_r (gcc)
3788 *Activate warnings for out-of-order record representation clauses.*
3790 This switch activates warnings for record representation clauses,
3791 if the order of component declarations, component clauses,
3792 and bit-level layout do not all agree.
3793 The default is that these warnings are not given.
3796 .. index:: -gnatw_R (gcc)
3799 *Suppress warnings for out-of-order record representation clauses.*
3802 .. index:: -gnatws (gcc)
3805 *Suppress all warnings.*
3807 This switch completely suppresses the
3808 output of all warning messages from the GNAT front end, including
3809 both warnings that can be controlled by switches described in this
3810 section, and those that are normally given unconditionally. The
3811 effect of this suppress action can only be cancelled by a subsequent
3812 use of the switch :switch:`-gnatwn`.
3814 Note that switch :switch:`-gnatws` does not suppress
3815 warnings from the ``gcc`` back end.
3816 To suppress these back end warnings as well, use the switch :switch:`-w`
3817 in addition to :switch:`-gnatws`. Also this switch has no effect on the
3818 handling of style check messages.
3821 .. index:: -gnatw.s (gcc)
3822 .. index:: Record Representation (component sizes)
3825 *Activate warnings on overridden size clauses.*
3827 This switch activates warnings on component clauses in record
3828 representation clauses where the length given overrides that
3829 specified by an explicit size clause for the component type. A
3830 warning is similarly given in the array case if a specified
3831 component size overrides an explicit size clause for the array
3835 .. index:: -gnatw.S (gcc)
3838 *Suppress warnings on overridden size clauses.*
3840 This switch suppresses warnings on component clauses in record
3841 representation clauses that override size clauses, and similar
3842 warnings when an array component size overrides a size clause.
3845 .. index:: -gnatw_s (gcc)
3849 *Activate warnings on ineffective predicate tests.*
3851 This switch activates warnings on Static_Predicate aspect
3852 specifications that test for values that do not belong to
3853 the parent subtype. Not all such ineffective tests are detected.
3855 .. index:: -gnatw_S (gcc)
3858 *Suppress warnings on ineffective predicate tests.*
3860 This switch suppresses warnings on Static_Predicate aspect
3861 specifications that test for values that do not belong to
3864 .. index:: -gnatwt (gcc)
3865 .. index:: Deactivated code, warnings
3866 .. index:: Deleted code, warnings
3869 *Activate warnings for tracking of deleted conditional code.*
3871 This switch activates warnings for tracking of code in conditionals (IF and
3872 CASE statements) that is detected to be dead code which cannot be executed, and
3873 which is removed by the front end. This warning is off by default. This may be
3874 useful for detecting deactivated code in certified applications.
3877 .. index:: -gnatwT (gcc)
3880 *Suppress warnings for tracking of deleted conditional code.*
3882 This switch suppresses warnings for tracking of deleted conditional code.
3885 .. index:: -gnatw.t (gcc)
3888 *Activate warnings on suspicious contracts.*
3890 This switch activates warnings on suspicious contracts. This includes
3891 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
3892 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3893 ``Contract_Cases``). A function postcondition or contract case is suspicious
3894 when no postcondition or contract case for this function mentions the result
3895 of the function. A procedure postcondition or contract case is suspicious
3896 when it only refers to the pre-state of the procedure, because in that case
3897 it should rather be expressed as a precondition. This switch also controls
3898 warnings on suspicious cases of expressions typically found in contracts like
3899 quantified expressions and uses of Update attribute. The default is that such
3900 warnings are generated.
3903 .. index:: -gnatw.T (gcc)
3906 *Suppress warnings on suspicious contracts.*
3908 This switch suppresses warnings on suspicious contracts.
3911 .. index:: -gnatwu (gcc)
3914 *Activate warnings on unused entities.*
3916 This switch activates warnings to be generated for entities that
3917 are declared but not referenced, and for units that are |withed|
3919 referenced. In the case of packages, a warning is also generated if
3920 no entities in the package are referenced. This means that if a with'ed
3921 package is referenced but the only references are in ``use``
3922 clauses or ``renames``
3923 declarations, a warning is still generated. A warning is also generated
3924 for a generic package that is |withed| but never instantiated.
3925 In the case where a package or subprogram body is compiled, and there
3926 is a |with| on the corresponding spec
3927 that is only referenced in the body,
3928 a warning is also generated, noting that the
3929 |with| can be moved to the body. The default is that
3930 such warnings are not generated.
3931 This switch also activates warnings on unreferenced formals
3932 (it includes the effect of :switch:`-gnatwf`).
3935 .. index:: -gnatwU (gcc)
3938 *Suppress warnings on unused entities.*
3940 This switch suppresses warnings for unused entities and packages.
3941 It also turns off warnings on unreferenced formals (and thus includes
3942 the effect of :switch:`-gnatwF`).
3945 .. index:: -gnatw.u (gcc)
3948 *Activate warnings on unordered enumeration types.*
3950 This switch causes enumeration types to be considered as conceptually
3951 unordered, unless an explicit pragma ``Ordered`` is given for the type.
3952 The effect is to generate warnings in clients that use explicit comparisons
3953 or subranges, since these constructs both treat objects of the type as
3954 ordered. (A *client* is defined as a unit that is other than the unit in
3955 which the type is declared, or its body or subunits.) Please refer to
3956 the description of pragma ``Ordered`` in the
3957 :title:`GNAT Reference Manual` for further details.
3958 The default is that such warnings are not generated.
3961 .. index:: -gnatw.U (gcc)
3964 *Deactivate warnings on unordered enumeration types.*
3966 This switch causes all enumeration types to be considered as ordered, so
3967 that no warnings are given for comparisons or subranges for any type.
3970 .. index:: -gnatwv (gcc)
3971 .. index:: Unassigned variable warnings
3974 *Activate warnings on unassigned variables.*
3976 This switch activates warnings for access to variables which
3977 may not be properly initialized. The default is that
3978 such warnings are generated. This switch will also be emitted when
3979 initializing an array or record object via the following aggregate:
3983 Array_Or_Record : XXX := (others => <>);
3985 unless the relevant type fully initializes all components.
3987 .. index:: -gnatwV (gcc)
3990 *Suppress warnings on unassigned variables.*
3992 This switch suppresses warnings for access to variables which
3993 may not be properly initialized.
3996 .. index:: -gnatw.v (gcc)
3997 .. index:: bit order warnings
4000 *Activate info messages for non-default bit order.*
4002 This switch activates messages (labeled "info", they are not warnings,
4003 just informational messages) about the effects of non-default bit-order
4004 on records to which a component clause is applied. The effect of specifying
4005 non-default bit ordering is a bit subtle (and changed with Ada 2005), so
4006 these messages, which are given by default, are useful in understanding the
4007 exact consequences of using this feature.
4010 .. index:: -gnatw.V (gcc)
4013 *Suppress info messages for non-default bit order.*
4015 This switch suppresses information messages for the effects of specifying
4016 non-default bit order on record components with component clauses.
4019 .. index:: -gnatww (gcc)
4020 .. index:: String indexing warnings
4023 *Activate warnings on wrong low bound assumption.*
4025 This switch activates warnings for indexing an unconstrained string parameter
4026 with a literal or S'Length. This is a case where the code is assuming that the
4027 low bound is one, which is in general not true (for example when a slice is
4028 passed). The default is that such warnings are generated.
4031 .. index:: -gnatwW (gcc)
4034 *Suppress warnings on wrong low bound assumption.*
4036 This switch suppresses warnings for indexing an unconstrained string parameter
4037 with a literal or S'Length. Note that this warning can also be suppressed
4038 in a particular case by adding an assertion that the lower bound is 1,
4039 as shown in the following example:
4043 procedure K (S : String) is
4044 pragma Assert (S'First = 1);
4048 .. index:: -gnatw.w (gcc)
4049 .. index:: Warnings Off control
4052 *Activate warnings on Warnings Off pragmas.*
4054 This switch activates warnings for use of ``pragma Warnings (Off, entity)``
4055 where either the pragma is entirely useless (because it suppresses no
4056 warnings), or it could be replaced by ``pragma Unreferenced`` or
4057 ``pragma Unmodified``.
4058 Also activates warnings for the case of
4059 Warnings (Off, String), where either there is no matching
4060 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
4061 The default is that these warnings are not given.
4064 .. index:: -gnatw.W (gcc)
4067 *Suppress warnings on unnecessary Warnings Off pragmas.*
4069 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
4072 .. index:: -gnatwx (gcc)
4073 .. index:: Export/Import pragma warnings
4076 *Activate warnings on Export/Import pragmas.*
4078 This switch activates warnings on Export/Import pragmas when
4079 the compiler detects a possible conflict between the Ada and
4080 foreign language calling sequences. For example, the use of
4081 default parameters in a convention C procedure is dubious
4082 because the C compiler cannot supply the proper default, so
4083 a warning is issued. The default is that such warnings are
4087 .. index:: -gnatwX (gcc)
4090 *Suppress warnings on Export/Import pragmas.*
4092 This switch suppresses warnings on Export/Import pragmas.
4093 The sense of this is that you are telling the compiler that
4094 you know what you are doing in writing the pragma, and it
4095 should not complain at you.
4098 .. index:: -gnatw.x (gcc)
4101 *Activate warnings for No_Exception_Propagation mode.*
4103 This switch activates warnings for exception usage when pragma Restrictions
4104 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
4105 explicit exception raises which are not covered by a local handler, and for
4106 exception handlers which do not cover a local raise. The default is that
4107 these warnings are given for units that contain exception handlers.
4111 *Disable warnings for No_Exception_Propagation mode.*
4113 This switch disables warnings for exception usage when pragma Restrictions
4114 (No_Exception_Propagation) is in effect.
4117 .. index:: -gnatwy (gcc)
4118 .. index:: Ada compatibility issues warnings
4121 *Activate warnings for Ada compatibility issues.*
4123 For the most part, newer versions of Ada are upwards compatible
4124 with older versions. For example, Ada 2005 programs will almost
4125 always work when compiled as Ada 2012.
4126 However there are some exceptions (for example the fact that
4127 ``some`` is now a reserved word in Ada 2012). This
4128 switch activates several warnings to help in identifying
4129 and correcting such incompatibilities. The default is that
4130 these warnings are generated. Note that at one point Ada 2005
4131 was called Ada 0Y, hence the choice of character.
4134 .. index:: -gnatwY (gcc)
4135 .. index:: Ada compatibility issues warnings
4138 *Disable warnings for Ada compatibility issues.*
4140 This switch suppresses the warnings intended to help in identifying
4141 incompatibilities between Ada language versions.
4144 .. index:: -gnatw.y (gcc)
4145 .. index:: Package spec needing body
4148 *Activate information messages for why package spec needs body.*
4150 There are a number of cases in which a package spec needs a body.
4151 For example, the use of pragma Elaborate_Body, or the declaration
4152 of a procedure specification requiring a completion. This switch
4153 causes information messages to be output showing why a package
4154 specification requires a body. This can be useful in the case of
4155 a large package specification which is unexpectedly requiring a
4156 body. The default is that such information messages are not output.
4159 .. index:: -gnatw.Y (gcc)
4160 .. index:: No information messages for why package spec needs body
4163 *Disable information messages for why package spec needs body.*
4165 This switch suppresses the output of information messages showing why
4166 a package specification needs a body.
4169 .. index:: -gnatwz (gcc)
4170 .. index:: Unchecked_Conversion warnings
4173 *Activate warnings on unchecked conversions.*
4175 This switch activates warnings for unchecked conversions
4176 where the types are known at compile time to have different
4177 sizes. The default is that such warnings are generated. Warnings are also
4178 generated for subprogram pointers with different conventions.
4181 .. index:: -gnatwZ (gcc)
4184 *Suppress warnings on unchecked conversions.*
4186 This switch suppresses warnings for unchecked conversions
4187 where the types are known at compile time to have different
4188 sizes or conventions.
4191 .. index:: -gnatw.z (gcc)
4192 .. index:: Size/Alignment warnings
4195 *Activate warnings for size not a multiple of alignment.*
4197 This switch activates warnings for cases of array and record types
4198 with specified ``Size`` and ``Alignment`` attributes where the
4199 size is not a multiple of the alignment, resulting in an object
4200 size that is greater than the specified size. The default
4201 is that such warnings are generated.
4204 .. index:: -gnatw.Z (gcc)
4205 .. index:: Size/Alignment warnings
4208 *Suppress warnings for size not a multiple of alignment.*
4210 This switch suppresses warnings for cases of array and record types
4211 with specified ``Size`` and ``Alignment`` attributes where the
4212 size is not a multiple of the alignment, resulting in an object
4213 size that is greater than the specified size. The warning can also
4214 be suppressed by giving an explicit ``Object_Size`` value.
4217 .. index:: -Wunused (gcc)
4220 The warnings controlled by the :switch:`-gnatw` switch are generated by
4221 the front end of the compiler. The GCC back end can provide
4222 additional warnings and they are controlled by the :switch:`-W` switch.
4223 For example, :switch:`-Wunused` activates back end
4224 warnings for entities that are declared but not referenced.
4227 .. index:: -Wuninitialized (gcc)
4229 :switch:`-Wuninitialized`
4230 Similarly, :switch:`-Wuninitialized` activates
4231 the back end warning for uninitialized variables. This switch must be
4232 used in conjunction with an optimization level greater than zero.
4235 .. index:: -Wstack-usage (gcc)
4237 :switch:`-Wstack-usage={len}`
4238 Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
4239 See :ref:`Static_Stack_Usage_Analysis` for details.
4242 .. index:: -Wall (gcc)
4245 This switch enables most warnings from the GCC back end.
4246 The code generator detects a number of warning situations that are missed
4247 by the GNAT front end, and this switch can be used to activate them.
4248 The use of this switch also sets the default front-end warning mode to
4249 :switch:`-gnatwa`, that is, most front-end warnings are activated as well.
4255 Conversely, this switch suppresses warnings from the GCC back end.
4256 The use of this switch also sets the default front-end warning mode to
4257 :switch:`-gnatws`, that is, front-end warnings are suppressed as well.
4260 .. index:: -Werror (gcc)
4263 This switch causes warnings from the GCC back end to be treated as
4264 errors. The warning string still appears, but the warning messages are
4265 counted as errors, and prevent the generation of an object file.
4266 The use of this switch also sets the default front-end warning mode to
4267 :switch:`-gnatwe`, that is, front-end warning messages and style check
4268 messages are treated as errors as well.
4271 A string of warning parameters can be used in the same parameter. For example::
4276 will turn on all optional warnings except for unrecognized pragma warnings,
4277 and also specify that warnings should be treated as errors.
4279 When no switch :switch:`-gnatw` is used, this is equivalent to:
4281 * :switch:`-gnatw.a`
4285 * :switch:`-gnatw.b`
4289 * :switch:`-gnatw.C`
4293 * :switch:`-gnatw.D`
4297 * :switch:`-gnatw.F`
4303 * :switch:`-gnatw.H`
4309 * :switch:`-gnatw.J`
4313 * :switch:`-gnatw.K`
4317 * :switch:`-gnatw.L`
4321 * :switch:`-gnatw.m`
4325 * :switch:`-gnatw.N`
4329 * :switch:`-gnatw.O`
4333 * :switch:`-gnatw.P`
4337 * :switch:`-gnatw.Q`
4341 * :switch:`-gnatw.R`
4343 * :switch:`-gnatw.S`
4347 * :switch:`-gnatw.t`
4351 * :switch:`-gnatw.U`
4355 * :switch:`-gnatw.v`
4359 * :switch:`-gnatw.W`
4363 * :switch:`-gnatw.X`
4367 * :switch:`-gnatw.Y`
4371 * :switch:`-gnatw.z`
4373 .. _Debugging_and_Assertion_Control:
4375 Debugging and Assertion Control
4376 -------------------------------
4380 .. index:: -gnata (gcc)
4385 .. index:: Assertions
4386 .. index:: Precondition
4387 .. index:: Postcondition
4388 .. index:: Type invariants
4389 .. index:: Subtype predicates
4391 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
4393 pragma Assertion_Policy (Check);
4395 Which is a shorthand for::
4397 pragma Assertion_Policy
4398 -- Ada RM assertion pragmas
4400 Static_Predicate => Check,
4401 Dynamic_Predicate => Check,
4405 Post'Class => Check,
4406 Type_Invariant => Check,
4407 Type_Invariant'Class => Check,
4408 Default_Initial_Condition => Check,
4409 -- GNAT specific assertion pragmas
4410 Assert_And_Cut => Check,
4412 Contract_Cases => Check,
4415 Initial_Condition => Check,
4416 Loop_Invariant => Check,
4417 Loop_Variant => Check,
4418 Postcondition => Check,
4419 Precondition => Check,
4421 Refined_Post => Check,
4422 Subprogram_Variant => Check);
4424 The pragmas ``Assert`` and ``Debug`` normally have no effect and
4425 are ignored. This switch, where ``a`` stands for 'assert', causes
4426 pragmas ``Assert`` and ``Debug`` to be activated. This switch also
4427 causes preconditions, postconditions, subtype predicates, and
4428 type invariants to be activated.
4430 The pragmas have the form::
4432 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4433 pragma Debug (<procedure call>)
4434 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4435 pragma Predicate (<type-local-name>, <Boolean-expression>)
4436 pragma Precondition (<Boolean-expression>, <string-expression>)
4437 pragma Postcondition (<Boolean-expression>, <string-expression>)
4439 The aspects have the form::
4441 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4442 => <Boolean-expression>;
4444 The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
4445 If the result is ``True``, the pragma has no effect (other than
4446 possible side effects from evaluating the expression). If the result is
4447 ``False``, the exception ``Assert_Failure`` declared in the package
4448 ``System.Assertions`` is raised (passing ``static-string-expression``, if
4449 present, as the message associated with the exception). If no string
4450 expression is given, the default is a string containing the file name and
4451 line number of the pragma.
4453 The ``Debug`` pragma causes ``procedure`` to be called. Note that
4454 ``pragma Debug`` may appear within a declaration sequence, allowing
4455 debugging procedures to be called between declarations.
4457 For the aspect specification, the ``Boolean-expression`` is evaluated.
4458 If the result is ``True``, the aspect has no effect. If the result
4459 is ``False``, the exception ``Assert_Failure`` is raised.
4461 .. _Validity_Checking:
4466 .. index:: Validity Checking
4468 The Ada Reference Manual defines the concept of invalid values (see
4469 RM 13.9.1). The primary source of invalid values is uninitialized
4470 variables. A scalar variable that is left uninitialized may contain
4471 an invalid value; the concept of invalid does not apply to access or
4474 It is an error to read an invalid value, but the RM does not require
4475 run-time checks to detect such errors, except for some minimal
4476 checking to prevent erroneous execution (i.e. unpredictable
4477 behavior). This corresponds to the :switch:`-gnatVd` switch below,
4478 which is the default. For example, by default, if the expression of a
4479 case statement is invalid, it will raise Constraint_Error rather than
4480 causing a wild jump, and if an array index on the left-hand side of an
4481 assignment is invalid, it will raise Constraint_Error rather than
4482 overwriting an arbitrary memory location.
4484 The :switch:`-gnatVa` may be used to enable additional validity checks,
4485 which are not required by the RM. These checks are often very
4486 expensive (which is why the RM does not require them). These checks
4487 are useful in tracking down uninitialized variables, but they are
4488 not usually recommended for production builds, and in particular
4489 we do not recommend using these extra validity checking options in
4490 combination with optimization, since this can confuse the optimizer.
4491 If performance is a consideration, leading to the need to optimize,
4492 then the validity checking options should not be used.
4494 The other :switch:`-gnatV{x}` switches below allow finer-grained
4495 control; you can enable whichever validity checks you desire. However,
4496 for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
4497 default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
4498 sufficient for non-debugging use.
4500 The :switch:`-gnatB` switch tells the compiler to assume that all
4501 values are valid (that is, within their declared subtype range)
4502 except in the context of a use of the Valid attribute. This means
4503 the compiler can generate more efficient code, since the range
4504 of values is better known at compile time. However, an uninitialized
4505 variable can cause wild jumps and memory corruption in this mode.
4507 The :switch:`-gnatV{x}` switch allows control over the validity
4508 checking mode as described below.
4509 The ``x`` argument is a string of letters that
4510 indicate validity checks that are performed or not performed in addition
4511 to the default checks required by Ada as described above.
4514 .. index:: -gnatVa (gcc)
4517 *All validity checks.*
4519 All validity checks are turned on.
4520 That is, :switch:`-gnatVa` is
4521 equivalent to ``gnatVcdefimoprst``.
4524 .. index:: -gnatVc (gcc)
4527 *Validity checks for copies.*
4529 The right-hand side of assignments, and the (explicit) initializing values
4530 of object declarations are validity checked.
4533 .. index:: -gnatVd (gcc)
4536 *Default (RM) validity checks.*
4538 Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these
4539 (and only these) validity checks are enabled by default.
4540 For case statements (and case expressions) that lack a "when others =>"
4541 choice, a check is made that the value of the selector expression
4542 belongs to its nominal subtype. If it does not, Constraint_Error is raised.
4543 For assignments to array components (and for indexed components in some
4544 other contexts), a check is made that each index expression belongs to the
4545 corresponding index subtype. If it does not, Constraint_Error is raised.
4546 Both these validity checks may be turned off using switch :switch:`-gnatVD`.
4547 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
4548 switch :switch:`-gnatVd` will leave the checks turned on.
4549 Switch :switch:`-gnatVD` should be used only if you are sure that all such
4550 expressions have valid values. If you use this switch and invalid values
4551 are present, then the program is erroneous, and wild jumps or memory
4552 overwriting may occur.
4555 .. index:: -gnatVe (gcc)
4558 *Validity checks for scalar components.*
4560 In the absence of this switch, assignments to scalar components of
4561 enclosing record or array objects are not validity checked, even if
4562 validity checks for assignments generally (:switch:`-gnatVc`) are turned on.
4563 Specifying this switch enables such checks.
4564 This switch has no effect if the :switch:`-gnatVc` switch is not specified.
4566 .. index:: -gnatVf (gcc)
4569 *Validity checks for floating-point values.*
4571 Specifying this switch enables validity checking for floating-point
4572 values in the same contexts where validity checking is enabled for
4573 other scalar values.
4574 In the absence of this switch, validity checking is not performed for
4575 floating-point values. This takes precedence over other statements about
4576 performing validity checking for scalar objects in various scenarios.
4577 One way to look at it is that if this switch is not set, then whenever
4578 any of the other rules in this section use the word "scalar" they
4579 really mean "scalar and not floating-point".
4580 If :switch:`-gnatVf` is specified, then validity checking also applies
4581 for floating-point values, and NaNs and infinities are considered invalid,
4582 as well as out-of-range values for constrained types. The exact contexts
4583 in which floating-point values are checked depends on the setting of other
4584 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
4585 (the order does not matter) specifies that floating-point parameters of mode
4586 ``in`` should be validity checked.
4589 .. index:: -gnatVi (gcc)
4592 *Validity checks for ``in`` mode parameters.*
4594 Arguments for parameters of mode ``in`` are validity checked in function
4595 and procedure calls at the point of call.
4598 .. index:: -gnatVm (gcc)
4601 *Validity checks for ``in out`` mode parameters.*
4603 Arguments for parameters of mode ``in out`` are validity checked in
4604 procedure calls at the point of call. The ``'m'`` here stands for
4605 modify, since this concerns parameters that can be modified by the call.
4606 Note that there is no specific option to test ``out`` parameters,
4607 but any reference within the subprogram will be tested in the usual
4608 manner, and if an invalid value is copied back, any reference to it
4609 will be subject to validity checking.
4612 .. index:: -gnatVn (gcc)
4615 *No validity checks.*
4617 This switch turns off all validity checking, including the default checking
4618 for case statements and left hand side subscripts. Note that the use of
4619 the switch :switch:`-gnatp` suppresses all run-time checks, including
4620 validity checks, and thus implies :switch:`-gnatVn`. When this switch
4621 is used, it cancels any other :switch:`-gnatV` previously issued.
4624 .. index:: -gnatVo (gcc)
4627 *Validity checks for operator and attribute operands.*
4629 Scalar arguments for predefined operators and for attributes are
4631 This includes all operators in package ``Standard``,
4632 the shift operators defined as intrinsic in package ``Interfaces``
4633 and operands for attributes such as ``Pos``. Checks are also made
4634 on individual component values for composite comparisons, and on the
4635 expressions in type conversions and qualified expressions. Checks are
4636 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4639 .. index:: -gnatVp (gcc)
4642 *Validity checks for parameters.*
4644 This controls the treatment of formal parameters within a subprogram (as
4645 opposed to :switch:`-gnatVi` and :switch:`-gnatVm`, which control validity
4646 testing of actual parameters of a call). If either of these call options is
4647 specified, then normally an assumption is made within a subprogram that
4648 the validity of any incoming formal parameters of the corresponding mode(s)
4649 has already been checked at the point of call and does not need rechecking.
4650 If :switch:`-gnatVp` is set, then this assumption is not made and so their
4651 validity may be checked (or rechecked) within the subprogram. If neither of
4652 the two call-related options is specified, then this switch has no effect.
4654 .. index:: -gnatVr (gcc)
4657 *Validity checks for function returns.*
4659 The expression in simple ``return`` statements in functions is validity
4663 .. index:: -gnatVs (gcc)
4666 *Validity checks for subscripts.*
4668 All subscript expressions are checked for validity, whatever context
4669 they occur in (in default mode some subscripts are not validity checked;
4670 for example, validity checking may be omitted in some cases involving
4671 a read of a component of an array).
4674 .. index:: -gnatVt (gcc)
4677 *Validity checks for tests.*
4679 Expressions used as conditions in ``if``, ``while`` or ``exit``
4680 statements are checked, as well as guard expressions in entry calls.
4683 The :switch:`-gnatV` switch may be followed by a string of letters
4684 to turn on a series of validity checking options.
4685 For example, :switch:`-gnatVcr`
4686 specifies that in addition to the default validity checking, copies and
4687 function return expressions are to be validity checked.
4688 In order to make it easier to specify the desired combination of effects,
4689 the upper case letters ``CDFIMORST`` may
4690 be used to turn off the corresponding lower case option.
4691 Thus :switch:`-gnatVaM` turns on all validity checking options except for
4692 checking of ``in out`` parameters.
4694 The specification of additional validity checking generates extra code (and
4695 in the case of :switch:`-gnatVa` the code expansion can be substantial).
4696 However, these additional checks can be very useful in detecting
4697 uninitialized variables, incorrect use of unchecked conversion, and other
4698 errors leading to invalid values. The use of pragma ``Initialize_Scalars``
4699 is useful in conjunction with the extra validity checking, since this
4700 ensures that wherever possible uninitialized variables have invalid values.
4702 See also the pragma ``Validity_Checks`` which allows modification of
4703 the validity checking mode at the program source level, and also allows for
4704 temporary disabling of validity checks.
4711 .. index:: Style checking
4713 .. index:: -gnaty (gcc)
4715 The :switch:`-gnaty` switch causes the compiler to
4716 enforce specified style rules. A limited set of style rules has been used
4717 in writing the GNAT sources themselves. This switch allows user programs
4718 to activate all or some of these checks. If the source program fails a
4719 specified style check, an appropriate message is given, preceded by
4720 the character sequence '(style)'. This message does not prevent
4721 successful compilation (unless the :switch:`-gnatwe` switch is used).
4723 Note that this is by no means intended to be a general facility for
4724 checking arbitrary coding standards. It is simply an embedding of the
4725 style rules we have chosen for the GNAT sources. If you are starting
4726 a project which does not have established style standards, you may
4727 find it useful to adopt the entire set of GNAT coding standards, or
4728 some subset of them.
4730 .. only:: PRO or GPL
4732 If you already have an established set of coding
4733 standards, then the selected style checking options may
4734 indeed correspond to choices you have made, but for general checking
4735 of an existing set of coding rules, you should look to the gnatcheck
4736 tool, which is designed for that purpose.
4738 The string ``x`` is a sequence of letters or digits
4739 indicating the particular style
4740 checks to be performed. The following checks are defined:
4743 .. index:: -gnaty[0-9] (gcc)
4746 *Specify indentation level.*
4748 If a digit from 1-9 appears
4749 in the string after :switch:`-gnaty`
4750 then proper indentation is checked, with the digit indicating the
4751 indentation level required. A value of zero turns off this style check.
4752 The rule checks that the following constructs start on a column that is
4753 a multiple of the alignment level:
4755 * beginnings of declarations (except record component declarations)
4758 * beginnings of the structural components of compound statements;
4760 * ``end`` keyword that completes the declaration of a program unit declaration
4761 or body or that completes a compound statement.
4763 Full line comments must be
4764 aligned with the ``--`` starting on a column that is a multiple of
4765 the alignment level, or they may be aligned the same way as the following
4766 non-blank line (this is useful when full line comments appear in the middle
4767 of a statement, or they may be aligned with the source line on the previous
4770 .. index:: -gnatya (gcc)
4773 *Check attribute casing.*
4775 Attribute names, including the case of keywords such as ``digits``
4776 used as attributes names, must be written in mixed case, that is, the
4777 initial letter and any letter following an underscore must be uppercase.
4778 All other letters must be lowercase.
4781 .. index:: -gnatyA (gcc)
4784 *Use of array index numbers in array attributes.*
4786 When using the array attributes First, Last, Range,
4787 or Length, the index number must be omitted for one-dimensional arrays
4788 and is required for multi-dimensional arrays.
4791 .. index:: -gnatyb (gcc)
4794 *Blanks not allowed at statement end.*
4796 Trailing blanks are not allowed at the end of statements. The purpose of this
4797 rule, together with h (no horizontal tabs), is to enforce a canonical format
4798 for the use of blanks to separate source tokens.
4801 .. index:: -gnatyB (gcc)
4804 *Check Boolean operators.*
4806 The use of AND/OR operators is not permitted except in the cases of modular
4807 operands, array operands, and simple stand-alone boolean variables or
4808 boolean constants. In all other cases ``and then``/`or else` are
4812 .. index:: -gnatyc (gcc)
4815 *Check comments, double space.*
4817 Comments must meet the following set of rules:
4819 * The ``--`` that starts the column must either start in column one,
4820 or else at least one blank must precede this sequence.
4822 * Comments that follow other tokens on a line must have at least one blank
4823 following the ``--`` at the start of the comment.
4825 * Full line comments must have at least two blanks following the
4826 ``--`` that starts the comment, with the following exceptions.
4828 * A line consisting only of the ``--`` characters, possibly preceded
4829 by blanks is permitted.
4831 * A comment starting with ``--x`` where ``x`` is a special character
4833 This allows proper processing of the output from specialized tools
4834 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
4836 language (where ``--#`` is used). For the purposes of this rule, a
4837 special character is defined as being in one of the ASCII ranges
4838 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
4839 Note that this usage is not permitted
4840 in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
4842 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4843 permitted. This allows the construction of box comments where lines of minus
4844 signs are used to form the top and bottom of the box.
4846 * A comment that starts and ends with ``--`` is permitted as long as at
4847 least one blank follows the initial ``--``. Together with the preceding
4848 rule, this allows the construction of box comments, as shown in the following
4853 ---------------------------
4854 -- This is a box comment --
4855 -- with two text lines. --
4856 ---------------------------
4859 .. index:: -gnatyC (gcc)
4862 *Check comments, single space.*
4864 This is identical to ``c`` except that only one space
4865 is required following the ``--`` of a comment instead of two.
4868 .. index:: -gnatyd (gcc)
4871 *Check no DOS line terminators present.*
4873 All lines must be terminated by a single ASCII.LF
4874 character (in particular the DOS line terminator sequence CR/LF is not
4878 .. index:: -gnatyD (gcc)
4881 *Check declared identifiers in mixed case.*
4883 Declared identifiers must be in mixed case, as in
4884 This_Is_An_Identifier. Use -gnatyr in addition to ensure
4885 that references match declarations.
4888 .. index:: -gnatye (gcc)
4891 *Check end/exit labels.*
4893 Optional labels on ``end`` statements ending subprograms and on
4894 ``exit`` statements exiting named loops, are required to be present.
4897 .. index:: -gnatyf (gcc)
4900 *No form feeds or vertical tabs.*
4902 Neither form feeds nor vertical tab characters are permitted
4906 .. index:: -gnatyg (gcc)
4911 The set of style check switches is set to match that used by the GNAT sources.
4912 This may be useful when developing code that is eventually intended to be
4913 incorporated into GNAT. Currently this is equivalent to
4914 :switch:`-gnatyydISuxz`) but additional style switches may be added to this
4915 set in the future without advance notice.
4918 .. index:: -gnatyh (gcc)
4921 *No horizontal tabs.*
4923 Horizontal tab characters are not permitted in the source text.
4924 Together with the b (no blanks at end of line) check, this
4925 enforces a canonical form for the use of blanks to separate
4929 .. index:: -gnatyi (gcc)
4932 *Check if-then layout.*
4934 The keyword ``then`` must appear either on the same
4935 line as corresponding ``if``, or on a line on its own, lined
4936 up under the ``if``.
4939 .. index:: -gnatyI (gcc)
4942 *check mode IN keywords.*
4944 Mode ``in`` (the default mode) is not
4945 allowed to be given explicitly. ``in out`` is fine,
4946 but not ``in`` on its own.
4949 .. index:: -gnatyk (gcc)
4952 *Check keyword casing.*
4954 All keywords must be in lower case (with the exception of keywords
4955 such as ``digits`` used as attribute names to which this check
4956 does not apply). A single error is reported for each line breaking
4957 this rule even if multiple casing issues exist on a same line.
4960 .. index:: -gnatyl (gcc)
4965 Layout of statement and declaration constructs must follow the
4966 recommendations in the Ada Reference Manual, as indicated by the
4967 form of the syntax rules. For example an ``else`` keyword must
4968 be lined up with the corresponding ``if`` keyword.
4970 There are two respects in which the style rule enforced by this check
4971 option are more liberal than those in the Ada Reference Manual. First
4972 in the case of record declarations, it is permissible to put the
4973 ``record`` keyword on the same line as the ``type`` keyword, and
4974 then the ``end`` in ``end record`` must line up under ``type``.
4975 This is also permitted when the type declaration is split on two lines.
4976 For example, any of the following three layouts is acceptable:
4997 Second, in the case of a block statement, a permitted alternative
4998 is to put the block label on the same line as the ``declare`` or
4999 ``begin`` keyword, and then line the ``end`` keyword up under
5000 the block label. For example both the following are permitted:
5017 The same alternative format is allowed for loops. For example, both of
5018 the following are permitted:
5022 Clear : while J < 10 loop
5032 .. index:: -gnatyLnnn (gcc)
5035 *Set maximum nesting level.*
5037 The maximum level of nesting of constructs (including subprograms, loops,
5038 blocks, packages, and conditionals) may not exceed the given value
5039 *nnn*. A value of zero disconnects this style check.
5042 .. index:: -gnatym (gcc)
5045 *Check maximum line length.*
5047 The length of source lines must not exceed 79 characters, including
5048 any trailing blanks. The value of 79 allows convenient display on an
5049 80 character wide device or window, allowing for possible special
5050 treatment of 80 character lines. Note that this count is of
5051 characters in the source text. This means that a tab character counts
5052 as one character in this count and a wide character sequence counts as
5053 a single character (however many bytes are needed in the encoding).
5056 .. index:: -gnatyMnnn (gcc)
5059 *Set maximum line length.*
5061 The length of lines must not exceed the
5062 given value *nnn*. The maximum value that can be specified is 32767.
5063 If neither style option for setting the line length is used, then the
5064 default is 255. This also controls the maximum length of lexical elements,
5065 where the only restriction is that they must fit on a single line.
5068 .. index:: -gnatyn (gcc)
5071 *Check casing of entities in Standard.*
5073 Any identifier from Standard must be cased
5074 to match the presentation in the Ada Reference Manual (for example,
5075 ``Integer`` and ``ASCII.NUL``).
5078 .. index:: -gnatyN (gcc)
5081 *Turn off all style checks.*
5083 All style check options are turned off.
5086 .. index:: -gnatyo (gcc)
5089 *Check order of subprogram bodies.*
5091 All subprogram bodies in a given scope
5092 (e.g., a package body) must be in alphabetical order. The ordering
5093 rule uses normal Ada rules for comparing strings, ignoring casing
5094 of letters, except that if there is a trailing numeric suffix, then
5095 the value of this suffix is used in the ordering (e.g., Junk2 comes
5099 .. index:: -gnatyO (gcc)
5102 *Check that overriding subprograms are explicitly marked as such.*
5104 This applies to all subprograms of a derived type that override a primitive
5105 operation of the type, for both tagged and untagged types. In particular,
5106 the declaration of a primitive operation of a type extension that overrides
5107 an inherited operation must carry an overriding indicator. Another case is
5108 the declaration of a function that overrides a predefined operator (such
5109 as an equality operator).
5112 .. index:: -gnatyp (gcc)
5115 *Check pragma casing.*
5117 Pragma names must be written in mixed case, that is, the
5118 initial letter and any letter following an underscore must be uppercase.
5119 All other letters must be lowercase. An exception is that SPARK_Mode is
5120 allowed as an alternative for Spark_Mode.
5123 .. index:: -gnatyr (gcc)
5128 All identifier references must be cased in the same way as the
5129 corresponding declaration. No specific casing style is imposed on
5130 identifiers. The only requirement is for consistency of references
5134 .. index:: -gnatys (gcc)
5137 *Check separate specs.*
5139 Separate declarations ('specs') are required for subprograms (a
5140 body is not allowed to serve as its own declaration). The only
5141 exception is that parameterless library level procedures are
5142 not required to have a separate declaration. This exception covers
5143 the most frequent form of main program procedures.
5146 .. index:: -gnatyS (gcc)
5149 *Check no statements after then/else.*
5151 No statements are allowed
5152 on the same line as a ``then`` or ``else`` keyword following the
5153 keyword in an ``if`` statement. ``or else`` and ``and then`` are not
5154 affected, and a special exception allows a pragma to appear after ``else``.
5157 .. index:: -gnatyt (gcc)
5160 *Check token spacing.*
5162 The following token spacing rules are enforced:
5164 * The keywords ``abs`` and ``not`` must be followed by a space.
5166 * The token ``=>`` must be surrounded by spaces.
5168 * The token ``<>`` must be preceded by a space or a left parenthesis.
5170 * Binary operators other than ``**`` must be surrounded by spaces.
5171 There is no restriction on the layout of the ``**`` binary operator.
5173 * Colon must be surrounded by spaces.
5175 * Colon-equal (assignment, initialization) must be surrounded by spaces.
5177 * Comma must be the first non-blank character on the line, or be
5178 immediately preceded by a non-blank character, and must be followed
5181 * If the token preceding a left parenthesis ends with a letter or digit, then
5182 a space must separate the two tokens.
5184 * If the token following a right parenthesis starts with a letter or digit, then
5185 a space must separate the two tokens.
5187 * A right parenthesis must either be the first non-blank character on
5188 a line, or it must be preceded by a non-blank character.
5190 * A semicolon must not be preceded by a space, and must not be followed by
5191 a non-blank character.
5193 * A unary plus or minus may not be followed by a space.
5195 * A vertical bar must be surrounded by spaces.
5197 Exactly one blank (and no other white space) must appear between
5198 a ``not`` token and a following ``in`` token.
5201 .. index:: -gnatyu (gcc)
5204 *Check unnecessary blank lines.*
5206 Unnecessary blank lines are not allowed. A blank line is considered
5207 unnecessary if it appears at the end of the file, or if more than
5208 one blank line occurs in sequence.
5211 .. index:: -gnatyx (gcc)
5214 *Check extra parentheses.*
5216 Unnecessary extra levels of parentheses (C-style) are not allowed
5217 around conditions (or selection expressions) in ``if``, ``while``,
5218 ``case``, and ``exit`` statements, as well as part of ranges.
5221 .. index:: -gnatyy (gcc)
5224 *Set all standard style check options.*
5226 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
5227 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
5228 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
5229 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
5232 .. index:: -gnatyz (gcc)
5235 *Check extra parentheses (operator precedence).*
5237 Extra levels of parentheses that are not required by operator precedence
5238 rules are flagged. See also ``-gnatyx``.
5241 .. index:: -gnaty- (gcc)
5244 *Remove style check options.*
5246 This causes any subsequent options in the string to act as canceling the
5247 corresponding style check option. To cancel maximum nesting level control,
5248 use the ``L`` parameter without any integer value after that, because any
5249 digit following *-* in the parameter string of the :switch:`-gnaty`
5250 option will be treated as canceling the indentation check. The same is true
5251 for the ``M`` parameter. ``y`` and ``N`` parameters are not
5255 .. index:: -gnaty+ (gcc)
5258 *Enable style check options.*
5260 This causes any subsequent options in the string to enable the corresponding
5261 style check option. That is, it cancels the effect of a previous -,
5265 .. end of switch description (leave this comment to ease automatic parsing for
5268 In the above rules, appearing in column one is always permitted, that is,
5269 counts as meeting either a requirement for a required preceding space,
5270 or as meeting a requirement for no preceding space.
5272 Appearing at the end of a line is also always permitted, that is, counts
5273 as meeting either a requirement for a following space, or as meeting
5274 a requirement for no following space.
5276 If any of these style rules is violated, a message is generated giving
5277 details on the violation. The initial characters of such messages are
5278 always '`(style)`'. Note that these messages are treated as warning
5279 messages, so they normally do not prevent the generation of an object
5280 file. The :switch:`-gnatwe` switch can be used to treat warning messages,
5281 including style messages, as fatal errors.
5283 The switch :switch:`-gnaty` on its own (that is not
5284 followed by any letters or digits) is equivalent
5285 to the use of :switch:`-gnatyy` as described above, that is all
5286 built-in standard style check options are enabled.
5288 The switch :switch:`-gnatyN` clears any previously set style checks.
5290 .. _Run-Time_Checks:
5295 .. index:: Division by zero
5297 .. index:: Access before elaboration
5299 .. index:: Checks, division by zero
5301 .. index:: Checks, access before elaboration
5303 .. index:: Checks, stack overflow checking
5305 By default, the following checks are suppressed: stack overflow
5306 checks, and checks for access before elaboration on subprogram
5307 calls. All other checks, including overflow checks, range checks and
5308 array bounds checks, are turned on by default. The following ``gcc``
5309 switches refine this default behavior.
5311 .. index:: -gnatp (gcc)
5314 .. index:: Suppressing checks
5316 .. index:: Checks, suppressing
5318 This switch causes the unit to be compiled
5319 as though ``pragma Suppress (All_checks)``
5320 had been present in the source. Validity checks are also eliminated (in
5321 other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
5322 Use this switch to improve the performance
5323 of the code at the expense of safety in the presence of invalid data or
5326 Note that when checks are suppressed, the compiler is allowed, but not
5327 required, to omit the checking code. If the run-time cost of the
5328 checking code is zero or near-zero, the compiler will generate it even
5329 if checks are suppressed. In particular, if the compiler can prove
5330 that a certain check will necessarily fail, it will generate code to
5331 do an unconditional 'raise', even if checks are suppressed. The
5332 compiler warns in this case. Another case in which checks may not be
5333 eliminated is when they are embedded in certain run-time routines such
5334 as math library routines.
5336 Of course, run-time checks are omitted whenever the compiler can prove
5337 that they will not fail, whether or not checks are suppressed.
5339 Note that if you suppress a check that would have failed, program
5340 execution is erroneous, which means the behavior is totally
5341 unpredictable. The program might crash, or print wrong answers, or
5342 do anything else. It might even do exactly what you wanted it to do
5343 (and then it might start failing mysteriously next week or next
5344 year). The compiler will generate code based on the assumption that
5345 the condition being checked is true, which can result in erroneous
5346 execution if that assumption is wrong.
5348 The checks subject to suppression include all the checks defined by the Ada
5349 standard, the additional implementation defined checks ``Alignment_Check``,
5350 ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``,
5351 and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``.
5352 Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option.
5354 If the code depends on certain checks being active, you can use
5355 pragma ``Unsuppress`` either as a configuration pragma or as
5356 a local pragma to make sure that a specified check is performed
5357 even if ``gnatp`` is specified.
5359 The :switch:`-gnatp` switch has no effect if a subsequent
5360 :switch:`-gnat-p` switch appears.
5363 .. index:: -gnat-p (gcc)
5364 .. index:: Suppressing checks
5365 .. index:: Checks, suppressing
5369 This switch cancels the effect of a previous ``gnatp`` switch.
5372 .. index:: -gnato?? (gcc)
5373 .. index:: Overflow checks
5374 .. index:: Overflow mode
5375 .. index:: Check, overflow
5378 This switch controls the mode used for computing intermediate
5379 arithmetic integer operations, and also enables overflow checking.
5380 For a full description of overflow mode and checking control, see
5381 the 'Overflow Check Handling in GNAT' appendix in this
5384 Overflow checks are always enabled by this switch. The argument
5385 controls the mode, using the codes
5389 In STRICT mode, intermediate operations are always done using the
5390 base type, and overflow checking ensures that the result is within
5391 the base type range.
5395 In MINIMIZED mode, overflows in intermediate operations are avoided
5396 where possible by using a larger integer type for the computation
5397 (typically ``Long_Long_Integer``). Overflow checking ensures that
5398 the result fits in this larger integer type.
5402 In ELIMINATED mode, overflows in intermediate operations are avoided
5403 by using multi-precision arithmetic. In this case, overflow checking
5404 has no effect on intermediate operations (since overflow is impossible).
5406 If two digits are present after :switch:`-gnato` then the first digit
5407 sets the mode for expressions outside assertions, and the second digit
5408 sets the mode for expressions within assertions. Here assertions is used
5409 in the technical sense (which includes for example precondition and
5410 postcondition expressions).
5412 If one digit is present, the corresponding mode is applicable to both
5413 expressions within and outside assertion expressions.
5415 If no digits are present, the default is to enable overflow checks
5416 and set STRICT mode for both kinds of expressions. This is compatible
5417 with the use of :switch:`-gnato` in previous versions of GNAT.
5419 .. index:: Machine_Overflows
5421 Note that the :switch:`-gnato??` switch does not affect the code generated
5422 for any floating-point operations; it applies only to integer semantics.
5423 For floating-point, GNAT has the ``Machine_Overflows``
5424 attribute set to ``False`` and the normal mode of operation is to
5425 generate IEEE NaN and infinite values on overflow or invalid operations
5426 (such as dividing 0.0 by 0.0).
5428 The reason that we distinguish overflow checking from other kinds of
5429 range constraint checking is that a failure of an overflow check, unlike
5430 for example the failure of a range check, can result in an incorrect
5431 value, but cannot cause random memory destruction (like an out of range
5432 subscript), or a wild jump (from an out of range case value). Overflow
5433 checking is also quite expensive in time and space, since in general it
5434 requires the use of double length arithmetic.
5436 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
5437 so overflow checking is performed in STRICT mode by default.
5440 .. index:: -gnatE (gcc)
5441 .. index:: Elaboration checks
5442 .. index:: Check, elaboration
5445 Enables dynamic checks for access-before-elaboration
5446 on subprogram calls and generic instantiations.
5447 Note that :switch:`-gnatE` is not necessary for safety, because in the
5448 default mode, GNAT ensures statically that the checks would not fail.
5449 For full details of the effect and use of this switch,
5450 :ref:`Compiling_with_gcc`.
5453 .. index:: -fstack-check (gcc)
5454 .. index:: Stack Overflow Checking
5455 .. index:: Checks, stack overflow checking
5457 :switch:`-fstack-check`
5458 Activates stack overflow checking. For full details of the effect and use of
5459 this switch see :ref:`Stack_Overflow_Checking`.
5461 .. index:: Unsuppress
5463 The setting of these switches only controls the default setting of the
5464 checks. You may modify them using either ``Suppress`` (to remove
5465 checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
5469 .. _Using_gcc_for_Syntax_Checking:
5471 Using ``gcc`` for Syntax Checking
5472 ---------------------------------
5474 .. index:: -gnats (gcc)
5477 The ``s`` stands for 'syntax'.
5479 Run GNAT in syntax checking only mode. For
5480 example, the command
5484 $ gcc -c -gnats x.adb
5486 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5487 series of files in a single command
5488 , and can use wildcards to specify such a group of files.
5489 Note that you must specify the :switch:`-c` (compile
5490 only) flag in addition to the :switch:`-gnats` flag.
5492 You may use other switches in conjunction with :switch:`-gnats`. In
5493 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
5494 format of any generated error messages.
5496 When the source file is empty or contains only empty lines and/or comments,
5497 the output is a warning:
5502 $ gcc -c -gnats -x ada toto.txt
5503 toto.txt:1:01: warning: empty file, contains no compilation units
5507 Otherwise, the output is simply the error messages, if any. No object file or
5508 ALI file is generated by a syntax-only compilation. Also, no units other
5509 than the one specified are accessed. For example, if a unit ``X``
5510 |withs| a unit ``Y``, compiling unit ``X`` in syntax
5511 check only mode does not access the source file containing unit
5514 .. index:: Multiple units, syntax checking
5516 Normally, GNAT allows only a single unit in a source file. However, this
5517 restriction does not apply in syntax-check-only mode, and it is possible
5518 to check a file containing multiple compilation units concatenated
5519 together. This is primarily used by the ``gnatchop`` utility
5520 (:ref:`Renaming_Files_with_gnatchop`).
5522 .. _Using_gcc_for_Semantic_Checking:
5524 Using ``gcc`` for Semantic Checking
5525 -----------------------------------
5529 .. index:: -gnatc (gcc)
5532 The ``c`` stands for 'check'.
5533 Causes the compiler to operate in semantic check mode,
5534 with full checking for all illegalities specified in the
5535 Ada Reference Manual, but without generation of any object code
5536 (no object file is generated).
5538 Because dependent files must be accessed, you must follow the GNAT
5539 semantic restrictions on file structuring to operate in this mode:
5541 * The needed source files must be accessible
5542 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5544 * Each file must contain only one compilation unit.
5546 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5548 The output consists of error messages as appropriate. No object file is
5549 generated. An :file:`ALI` file is generated for use in the context of
5550 cross-reference tools, but this file is marked as not being suitable
5551 for binding (since no object file is generated).
5552 The checking corresponds exactly to the notion of
5553 legality in the Ada Reference Manual.
5555 Any unit can be compiled in semantics-checking-only mode, including
5556 units that would not normally be compiled (subunits,
5557 and specifications where a separate body is present).
5559 .. _Compiling_Different_Versions_of_Ada:
5561 Compiling Different Versions of Ada
5562 -----------------------------------
5564 The switches described in this section allow you to explicitly specify
5565 the version of the Ada language that your programs are written in.
5566 The default mode is Ada 2012,
5567 but you can also specify Ada 95, Ada 2005 mode, or
5568 indicate Ada 83 compatibility mode.
5571 .. index:: Compatibility with Ada 83
5572 .. index:: -gnat83 (gcc)
5573 .. index:: ACVC, Ada 83 tests
5574 .. index:: Ada 83 mode
5576 :switch:`-gnat83` (Ada 83 Compatibility Mode)
5577 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5578 specifies that the program is to be compiled in Ada 83 mode. With
5579 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5580 semantics where this can be done easily.
5581 It is not possible to guarantee this switch does a perfect
5582 job; some subtle tests, such as are
5583 found in earlier ACVC tests (and that have been removed from the ACATS suite
5584 for Ada 95), might not compile correctly.
5585 Nevertheless, this switch may be useful in some circumstances, for example
5586 where, due to contractual reasons, existing code needs to be maintained
5587 using only Ada 83 features.
5589 With few exceptions (most notably the need to use ``<>`` on
5590 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5591 the use of the new Ada 95 / Ada 2005
5592 reserved words, and the use of packages
5593 with optional bodies), it is not necessary to specify the
5594 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
5595 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5596 a correct Ada 83 program is usually also a correct program
5597 in these later versions of the language standard. For further information
5598 please refer to the *Compatibility and Porting Guide* chapter in the
5599 :title:`GNAT Reference Manual`.
5602 .. index:: -gnat95 (gcc)
5603 .. index:: Ada 95 mode
5605 :switch:`-gnat95` (Ada 95 mode)
5606 This switch directs the compiler to implement the Ada 95 version of the
5608 Since Ada 95 is almost completely upwards
5609 compatible with Ada 83, Ada 83 programs may generally be compiled using
5610 this switch (see the description of the :switch:`-gnat83` switch for further
5611 information about Ada 83 mode).
5612 If an Ada 2005 program is compiled in Ada 95 mode,
5613 uses of the new Ada 2005 features will cause error
5614 messages or warnings.
5616 This switch also can be used to cancel the effect of a previous
5617 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
5618 switch earlier in the command line.
5621 .. index:: -gnat05 (gcc)
5622 .. index:: -gnat2005 (gcc)
5623 .. index:: Ada 2005 mode
5625 :switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
5626 This switch directs the compiler to implement the Ada 2005 version of the
5627 language, as documented in the official Ada standards document.
5628 Since Ada 2005 is almost completely upwards
5629 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5630 may generally be compiled using this switch (see the description of the
5631 :switch:`-gnat83` and :switch:`-gnat95` switches for further
5635 .. index:: -gnat12 (gcc)
5636 .. index:: -gnat2012 (gcc)
5637 .. index:: Ada 2012 mode
5639 :switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
5640 This switch directs the compiler to implement the Ada 2012 version of the
5641 language (also the default).
5642 Since Ada 2012 is almost completely upwards
5643 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5644 Ada 83 and Ada 95 programs
5645 may generally be compiled using this switch (see the description of the
5646 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
5647 for further information).
5650 .. index:: -gnat2022 (gcc)
5651 .. index:: Ada 2022 mode
5653 :switch:`-gnat2022` (Ada 2022 mode)
5654 This switch directs the compiler to implement the Ada 2022 version of the
5658 .. index:: -gnatX0 (gcc)
5659 .. index:: Ada language extensions
5660 .. index:: GNAT extensions
5662 :switch:`-gnatX0` (Enable GNAT Extensions)
5663 This switch directs the compiler to implement the latest version of the
5664 language (currently Ada 2022) and also to enable certain GNAT implementation
5665 extensions that are not part of any Ada standard. For a full list of these
5666 extensions, see the GNAT reference manual, ``Pragma Extensions_Allowed``.
5668 .. index:: -gnatX (gcc)
5669 .. index:: Ada language extensions
5670 .. index:: GNAT extensions
5672 :switch:`-gnatX` (Enable core GNAT Extensions)
5673 This switch is similar to -gnatX0 except that only some, not all, of the
5674 GNAT-defined language extensions are enabled. For a list of the
5675 extensions enabled by this switch, see the GNAT reference manual
5676 ``Pragma Extensions_Allowed`` and the description of that pragma's
5677 "On" (as opposed to "All") argument.
5680 .. _Character_Set_Control:
5682 Character Set Control
5683 ---------------------
5685 .. index:: -gnati (gcc)
5688 Normally GNAT recognizes the Latin-1 character set in source program
5689 identifiers, as described in the Ada Reference Manual.
5691 GNAT to recognize alternate character sets in identifiers. ``c`` is a
5692 single character indicating the character set, as follows:
5694 ========== ======================================================
5695 *1* ISO 8859-1 (Latin-1) identifiers
5696 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5697 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5698 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5699 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5700 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5701 *p* IBM PC letters (code page 437) allowed in identifiers
5702 *8* IBM PC letters (code page 850) allowed in identifiers
5703 *f* Full upper-half codes allowed in identifiers
5704 *n* No upper-half codes allowed in identifiers
5705 *w* Wide-character codes (that is, codes greater than 255)
5706 allowed in identifiers
5707 ========== ======================================================
5709 See :ref:`Foreign_Language_Representation` for full details on the
5710 implementation of these character sets.
5713 .. index:: -gnatW (gcc)
5716 Specify the method of encoding for wide characters.
5717 ``e`` is one of the following:
5719 ========== ======================================================
5720 *h* Hex encoding (brackets coding also recognized)
5721 *u* Upper half encoding (brackets encoding also recognized)
5722 *s* Shift/JIS encoding (brackets encoding also recognized)
5723 *e* EUC encoding (brackets encoding also recognized)
5724 *8* UTF-8 encoding (brackets encoding also recognized)
5725 *b* Brackets encoding only (default value)
5726 ========== ======================================================
5728 For full details on these encoding
5729 methods see :ref:`Wide_Character_Encodings`.
5730 Note that brackets coding is always accepted, even if one of the other
5731 options is specified, so for example :switch:`-gnatW8` specifies that both
5732 brackets and UTF-8 encodings will be recognized. The units that are
5733 with'ed directly or indirectly will be scanned using the specified
5734 representation scheme, and so if one of the non-brackets scheme is
5735 used, it must be used consistently throughout the program. However,
5736 since brackets encoding is always recognized, it may be conveniently
5737 used in standard libraries, allowing these libraries to be used with
5738 any of the available coding schemes.
5740 Note that brackets encoding only applies to program text. Within comments,
5741 brackets are considered to be normal graphic characters, and bracket sequences
5742 are never recognized as wide characters.
5744 If no :switch:`-gnatW?` parameter is present, then the default
5745 representation is normally Brackets encoding only. However, if the
5746 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5747 byte order mark or BOM for UTF-8), then these three characters are
5748 skipped and the default representation for the file is set to UTF-8.
5750 Note that the wide character representation that is specified (explicitly
5751 or by default) for the main program also acts as the default encoding used
5752 for Wide_Text_IO files if not specifically overridden by a WCEM form
5756 When no :switch:`-gnatW?` is specified, then characters (other than wide
5757 characters represented using brackets notation) are treated as 8-bit
5758 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5759 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5760 characters in the range 16#00#..16#1F# are not accepted in program text
5761 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5762 in program text, but allowed and ignored in comments. Note in particular
5763 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5764 as an end of line in this default mode. If your source program contains
5765 instances of the NEL character used as a line terminator,
5766 you must use UTF-8 encoding for the whole
5767 source program. In default mode, all lines must be ended by a standard
5768 end of line sequence (CR, CR/LF, or LF).
5770 Note that the convention of simply accepting all upper half characters in
5771 comments means that programs that use standard ASCII for program text, but
5772 UTF-8 encoding for comments are accepted in default mode, providing that the
5773 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5774 This is a common mode for many programs with foreign language comments.
5776 .. _File_Naming_Control:
5781 .. index:: -gnatk (gcc)
5784 Activates file name 'krunching'. ``n``, a decimal integer in the range
5785 1-999, indicates the maximum allowable length of a file name (not
5786 including the :file:`.ads` or :file:`.adb` extension). The default is not
5787 to enable file name krunching.
5789 For the source file naming rules, :ref:`File_Naming_Rules`.
5791 .. _Subprogram_Inlining_Control:
5793 Subprogram Inlining Control
5794 ---------------------------
5796 .. index:: -gnatn (gcc)
5798 :switch:`-gnatn[12]`
5799 The ``n`` here is intended to suggest the first syllable of the word 'inline'.
5800 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
5801 actually occur, optimization must be enabled and, by default, inlining of
5802 subprograms across units is not performed. If you want to additionally
5803 enable inlining of subprograms specified by pragma ``Inline`` across units,
5804 you must also specify this switch.
5806 In the absence of this switch, GNAT does not attempt inlining across units
5807 and does not access the bodies of subprograms for which ``pragma Inline`` is
5808 specified if they are not in the current unit.
5810 You can optionally specify the inlining level: 1 for moderate inlining across
5811 units, which is a good compromise between compilation times and performances
5812 at run time, or 2 for full inlining across units, which may bring about
5813 longer compilation times. If no inlining level is specified, the compiler will
5814 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
5815 :switch:`-Os` and 2 for :switch:`-O3`.
5817 If you specify this switch the compiler will access these bodies,
5818 creating an extra source dependency for the resulting object file, and
5819 where possible, the call will be inlined.
5820 For further details on when inlining is possible
5821 see :ref:`Inlining_of_Subprograms`.
5824 .. index:: -gnatN (gcc)
5827 This switch activates front-end inlining which also
5828 generates additional dependencies.
5830 When using a gcc-based back end, then the use of
5831 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
5832 Historically front end inlining was more extensive than the gcc back end
5833 inlining, but that is no longer the case.
5835 .. _Auxiliary_Output_Control:
5837 Auxiliary Output Control
5838 ------------------------
5840 .. index:: -gnatu (gcc)
5843 Print a list of units required by this compilation on :file:`stdout`.
5844 The listing includes all units on which the unit being compiled depends
5845 either directly or indirectly.
5848 .. index:: -pass-exit-codes (gcc)
5850 :switch:`-pass-exit-codes`
5851 If this switch is not used, the exit code returned by ``gcc`` when
5852 compiling multiple files indicates whether all source files have
5853 been successfully used to generate object files or not.
5855 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
5856 exit status and allows an integrated development environment to better
5857 react to a compilation failure. Those exit status are:
5859 ========== ======================================================
5860 *5* There was an error in at least one source file.
5861 *3* At least one source file did not generate an object file.
5862 *2* The compiler died unexpectedly (internal error for example).
5863 *0* An object file has been generated for every source file.
5864 ========== ======================================================
5866 .. _Debugging_Control:
5871 .. index:: Debugging options
5874 .. index:: -gnatd (gcc)
5877 Activate internal debugging switches. ``x`` is a letter or digit, or
5878 string of letters or digits, which specifies the type of debugging
5879 outputs desired. Normally these are used only for internal development
5880 or system debugging purposes. You can find full documentation for these
5881 switches in the body of the ``Debug`` unit in the compiler source
5882 file :file:`debug.adb`.
5885 .. index:: -gnatG (gcc)
5887 :switch:`-gnatG[={nn}]`
5888 This switch causes the compiler to generate auxiliary output containing
5889 a pseudo-source listing of the generated expanded code. Like most Ada
5890 compilers, GNAT works by first transforming the high level Ada code into
5891 lower level constructs. For example, tasking operations are transformed
5892 into calls to the tasking run-time routines. A unique capability of GNAT
5893 is to list this expanded code in a form very close to normal Ada source.
5894 This is very useful in understanding the implications of various Ada
5895 usage on the efficiency of the generated code. There are many cases in
5896 Ada (e.g., the use of controlled types), where simple Ada statements can
5897 generate a lot of run-time code. By using :switch:`-gnatG` you can identify
5898 these cases, and consider whether it may be desirable to modify the coding
5899 approach to improve efficiency.
5901 The optional parameter ``nn`` if present after -gnatG specifies an
5902 alternative maximum line length that overrides the normal default of 72.
5903 This value is in the range 40-999999, values less than 40 being silently
5904 reset to 40. The equal sign is optional.
5906 The format of the output is very similar to standard Ada source, and is
5907 easily understood by an Ada programmer. The following special syntactic
5908 additions correspond to low level features used in the generated code that
5909 do not have any exact analogies in pure Ada source form. The following
5910 is a partial list of these special constructions. See the spec
5911 of package ``Sprint`` in file :file:`sprint.ads` for a full list.
5913 .. index:: -gnatL (gcc)
5915 If the switch :switch:`-gnatL` is used in conjunction with
5916 :switch:`-gnatG`, then the original source lines are interspersed
5917 in the expanded source (as comment lines with the original line number).
5919 :samp:`new {xxx} [storage_pool = {yyy}]`
5920 Shows the storage pool being used for an allocator.
5923 :samp:`at end {procedure-name};`
5924 Shows the finalization (cleanup) procedure for a scope.
5927 :samp:`(if {expr} then {expr} else {expr})`
5928 Conditional expression equivalent to the ``x?y:z`` construction in C.
5931 :samp:`{target}^({source})`
5932 A conversion with floating-point truncation instead of rounding.
5935 :samp:`{target}?({source})`
5936 A conversion that bypasses normal Ada semantic checking. In particular
5937 enumeration types and fixed-point types are treated simply as integers.
5940 :samp:`{target}?^({source})`
5941 Combines the above two cases.
5946 :samp:`{x} #mod {y}`
5950 :samp:`{x} #rem {y}`
5951 A division or multiplication of fixed-point values which are treated as
5952 integers without any kind of scaling.
5955 :samp:`free {expr} [storage_pool = {xxx}]`
5956 Shows the storage pool associated with a ``free`` statement.
5959 :samp:`[subtype or type declaration]`
5960 Used to list an equivalent declaration for an internally generated
5961 type that is referenced elsewhere in the listing.
5964 :samp:`freeze {type-name} [{actions}]`
5965 Shows the point at which ``type-name`` is frozen, with possible
5966 associated actions to be performed at the freeze point.
5969 :samp:`reference {itype}`
5970 Reference (and hence definition) to internal type ``itype``.
5973 :samp:`{function-name}! ({arg}, {arg}, {arg})`
5974 Intrinsic function call.
5977 :samp:`{label-name} : label`
5978 Declaration of label ``labelname``.
5981 :samp:`#$ {subprogram-name}`
5982 An implicit call to a run-time support routine
5983 (to meet the requirement of H.3.1(9) in a
5987 :samp:`{expr} && {expr} && {expr} ... && {expr}`
5988 A multiple concatenation (same effect as ``expr`` & ``expr`` &
5989 ``expr``, but handled more efficiently).
5992 :samp:`[constraint_error]`
5993 Raise the ``Constraint_Error`` exception.
5996 :samp:`{expression}'reference`
5997 A pointer to the result of evaluating {expression}.
6000 :samp:`{target-type}!({source-expression})`
6001 An unchecked conversion of ``source-expression`` to ``target-type``.
6004 :samp:`[{numerator}/{denominator}]`
6005 Used to represent internal real literals (that) have no exact
6006 representation in base 2-16 (for example, the result of compile time
6007 evaluation of the expression 1.0/27.0).
6010 .. index:: -gnatD (gcc)
6012 :switch:`-gnatD[=nn]`
6013 When used in conjunction with :switch:`-gnatG`, this switch causes
6014 the expanded source, as described above for
6015 :switch:`-gnatG` to be written to files with names
6016 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
6017 instead of to the standard output file. For
6018 example, if the source file name is :file:`hello.adb`, then a file
6019 :file:`hello.adb.dg` will be written. The debugging
6020 information generated by the ``gcc`` :switch:`-g` switch
6021 will refer to the generated :file:`xxx.dg` file. This allows
6022 you to do source level debugging using the generated code which is
6023 sometimes useful for complex code, for example to find out exactly
6024 which part of a complex construction raised an exception. This switch
6025 also suppresses generation of cross-reference information (see
6026 :switch:`-gnatx`) since otherwise the cross-reference information
6027 would refer to the :file:`.dg` file, which would cause
6028 confusion since this is not the original source file.
6030 Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
6031 automatically, so it is not necessary to give both options.
6032 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
6034 .. index:: -gnatL (gcc)
6036 If the switch :switch:`-gnatL` is used in conjunction with
6037 :switch:`-gnatDG`, then the original source lines are interspersed
6038 in the expanded source (as comment lines with the original line number).
6040 The optional parameter ``nn`` if present after -gnatD specifies an
6041 alternative maximum line length that overrides the normal default of 72.
6042 This value is in the range 40-999999, values less than 40 being silently
6043 reset to 40. The equal sign is optional.
6046 .. index:: -gnatr (gcc)
6047 .. index:: pragma Restrictions
6050 This switch causes pragma Restrictions to be treated as Restriction_Warnings
6051 so that violation of restrictions causes warnings rather than illegalities.
6052 This is useful during the development process when new restrictions are added
6053 or investigated. The switch also causes pragma Profile to be treated as
6054 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
6055 restriction warnings rather than restrictions.
6058 .. index:: -gnatR (gcc)
6060 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
6061 This switch controls output from the compiler of a listing showing
6062 representation information for declared types, objects and subprograms.
6063 For :switch:`-gnatR0`, no information is output (equivalent to omitting
6064 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
6065 so :switch:`-gnatR` with no parameter has the same effect), size and
6066 alignment information is listed for declared array and record types.
6068 For :switch:`-gnatR2`, size and alignment information is listed for all
6069 declared types and objects. The ``Linker_Section`` is also listed for any
6070 entity for which the ``Linker_Section`` is set explicitly or implicitly (the
6071 latter case occurs for objects of a type for which a ``Linker_Section``
6074 For :switch:`-gnatR3`, symbolic expressions for values that are computed
6075 at run time for records are included. These symbolic expressions have
6076 a mostly obvious format with #n being used to represent the value of the
6077 n'th discriminant. See source files :file:`repinfo.ads/adb` in the
6078 GNAT sources for full details on the format of :switch:`-gnatR3` output.
6080 For :switch:`-gnatR4`, information for relevant compiler-generated types
6081 is also listed, i.e. when they are structurally part of other declared
6084 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
6085 extended representation information for record sub-components of records
6088 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
6089 subprogram conventions and parameter passing mechanisms for all the
6090 subprograms are included.
6092 If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
6093 the output is in the JSON data interchange format specified by the
6094 ECMA-404 standard. The semantic description of this JSON output is
6095 available in the specification of the Repinfo unit present in the
6098 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
6099 the output is to a file with the name :file:`file.rep` where ``file`` is
6100 the name of the corresponding source file, except if ``j`` is also
6101 specified, in which case the file name is :file:`file.json`.
6103 Note that it is possible for record components to have zero size. In
6104 this case, the component clause uses an obvious extension of permitted
6105 Ada syntax, for example ``at 0 range 0 .. -1``.
6108 .. index:: -gnatS (gcc)
6111 The use of the switch :switch:`-gnatS` for an
6112 Ada compilation will cause the compiler to output a
6113 representation of package Standard in a form very
6114 close to standard Ada. It is not quite possible to
6115 do this entirely in standard Ada (since new
6116 numeric base types cannot be created in standard
6117 Ada), but the output is easily
6118 readable to any Ada programmer, and is useful to
6119 determine the characteristics of target dependent
6120 types in package Standard.
6123 .. index:: -gnatx (gcc)
6126 Normally the compiler generates full cross-referencing information in
6127 the :file:`ALI` file. This information is used by a number of tools.
6128 The :switch:`-gnatx` switch suppresses this information. This saves some space
6129 and may slightly speed up compilation, but means that tools depending
6130 on this information cannot be used.
6133 .. index:: -fgnat-encodings (gcc)
6135 :switch:`-fgnat-encodings=[all|gdb|minimal]`
6136 This switch controls the balance between GNAT encodings and standard DWARF
6137 emitted in the debug information.
6139 Historically, old debug formats like stabs were not powerful enough to
6140 express some Ada types (for instance, variant records or fixed-point types).
6141 To work around this, GNAT introduced proprietary encodings that embed the
6142 missing information ("GNAT encodings").
6144 Recent versions of the DWARF debug information format are now able to
6145 correctly describe most of these Ada constructs ("standard DWARF"). As
6146 third-party tools started to use this format, GNAT has been enhanced to
6147 generate it. However, most tools (including GDB) are still relying on GNAT
6150 To support all tools, GNAT needs to be versatile about the balance between
6151 generation of GNAT encodings and standard DWARF. This is what
6152 :switch:`-fgnat-encodings` is about.
6154 * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as
6155 possible so it does not conflict with GNAT encodings.
6156 * ``=gdb``: Emit as much standard DWARF as possible as long as the current
6157 GDB handles it. Emit GNAT encodings for the rest.
6158 * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT
6159 encodings for the rest.
6162 .. _Exception_Handling_Control:
6164 Exception Handling Control
6165 --------------------------
6167 GNAT uses two methods for handling exceptions at run time. The
6168 ``setjmp/longjmp`` method saves the context when entering
6169 a frame with an exception handler. Then when an exception is
6170 raised, the context can be restored immediately, without the
6171 need for tracing stack frames. This method provides very fast
6172 exception propagation, but introduces significant overhead for
6173 the use of exception handlers, even if no exception is raised.
6175 The other approach is called 'zero cost' exception handling.
6176 With this method, the compiler builds static tables to describe
6177 the exception ranges. No dynamic code is required when entering
6178 a frame containing an exception handler. When an exception is
6179 raised, the tables are used to control a back trace of the
6180 subprogram invocation stack to locate the required exception
6181 handler. This method has considerably poorer performance for
6182 the propagation of exceptions, but there is no overhead for
6183 exception handlers if no exception is raised. Note that in this
6184 mode and in the context of mixed Ada and C/C++ programming,
6185 to propagate an exception through a C/C++ code, the C/C++ code
6186 must be compiled with the :switch:`-funwind-tables` GCC's
6189 The following switches may be used to control which of the
6190 two exception handling methods is used.
6194 .. index:: --RTS=sjlj (gnatmake)
6196 :switch:`--RTS=sjlj`
6197 This switch causes the setjmp/longjmp run-time (when available) to be used
6198 for exception handling. If the default
6199 mechanism for the target is zero cost exceptions, then
6200 this switch can be used to modify this default, and must be
6201 used for all units in the partition.
6202 This option is rarely used. One case in which it may be
6203 advantageous is if you have an application where exception
6204 raising is common and the overall performance of the
6205 application is improved by favoring exception propagation.
6208 .. index:: --RTS=zcx (gnatmake)
6209 .. index:: Zero Cost Exceptions
6212 This switch causes the zero cost approach to be used
6213 for exception handling. If this is the default mechanism for the
6214 target (see below), then this switch is unneeded. If the default
6215 mechanism for the target is setjmp/longjmp exceptions, then
6216 this switch can be used to modify this default, and must be
6217 used for all units in the partition.
6218 This option can only be used if the zero cost approach
6219 is available for the target in use, otherwise it will generate an error.
6221 The same option :switch:`--RTS` must be used both for ``gcc``
6222 and ``gnatbind``. Passing this option to ``gnatmake``
6223 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
6224 through the compilation and binding steps.
6226 .. _Units_to_Sources_Mapping_Files:
6228 Units to Sources Mapping Files
6229 ------------------------------
6233 .. index:: -gnatem (gcc)
6235 :switch:`-gnatem={path}`
6236 A mapping file is a way to communicate to the compiler two mappings:
6237 from unit names to file names (without any directory information) and from
6238 file names to path names (with full directory information). These mappings
6239 are used by the compiler to short-circuit the path search.
6241 The use of mapping files is not required for correct operation of the
6242 compiler, but mapping files can improve efficiency, particularly when
6243 sources are read over a slow network connection. In normal operation,
6244 you need not be concerned with the format or use of mapping files,
6245 and the :switch:`-gnatem` switch is not a switch that you would use
6246 explicitly. It is intended primarily for use by automatic tools such as
6247 ``gnatmake`` running under the project file facility. The
6248 description here of the format of mapping files is provided
6249 for completeness and for possible use by other tools.
6251 A mapping file is a sequence of sets of three lines. In each set, the
6252 first line is the unit name, in lower case, with ``%s`` appended
6253 for specs and ``%b`` appended for bodies; the second line is the
6254 file name; and the third line is the path name.
6260 /gnat/project1/sources/main.2.ada
6263 When the switch :switch:`-gnatem` is specified, the compiler will
6264 create in memory the two mappings from the specified file. If there is
6265 any problem (nonexistent file, truncated file or duplicate entries),
6266 no mapping will be created.
6268 Several :switch:`-gnatem` switches may be specified; however, only the
6269 last one on the command line will be taken into account.
6271 When using a project file, ``gnatmake`` creates a temporary
6272 mapping file and communicates it to the compiler using this switch.
6275 .. _Code_Generation_Control:
6277 Code Generation Control
6278 -----------------------
6280 The GCC technology provides a wide range of target dependent
6281 :switch:`-m` switches for controlling
6282 details of code generation with respect to different versions of
6283 architectures. This includes variations in instruction sets (e.g.,
6284 different members of the power pc family), and different requirements
6285 for optimal arrangement of instructions (e.g., different members of
6286 the x86 family). The list of available :switch:`-m` switches may be
6287 found in the GCC documentation.
6289 Use of these :switch:`-m` switches may in some cases result in improved
6292 The GNAT technology is tested and qualified without any
6293 :switch:`-m` switches,
6294 so generally the most reliable approach is to avoid the use of these
6295 switches. However, we generally expect most of these switches to work
6296 successfully with GNAT, and many customers have reported successful
6297 use of these options.
6299 Our general advice is to avoid the use of :switch:`-m` switches unless
6300 special needs lead to requirements in this area. In particular,
6301 there is no point in using :switch:`-m` switches to improve performance
6302 unless you actually see a performance improvement.
6305 .. _Linker_Switches:
6310 Linker switches can be specified after :switch:`-largs` builder switch.
6312 .. index:: -fuse-ld=name
6314 :switch:`-fuse-ld={name}`
6315 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`; ``gold``
6316 (for :file:`ld.gold`) and ``mold`` (for :file:`ld.mold`) are more
6317 recent and faster alternatives, but only available on GNU/Linux
6320 .. _Binding_with_gnatbind:
6322 Binding with ``gnatbind``
6323 =========================
6325 .. index:: ! gnatbind
6327 This chapter describes the GNAT binder, ``gnatbind``, which is used
6328 to bind compiled GNAT objects.
6330 The ``gnatbind`` program performs four separate functions:
6332 * Checks that a program is consistent, in accordance with the rules in
6333 Chapter 10 of the Ada Reference Manual. In particular, error
6334 messages are generated if a program uses inconsistent versions of a
6337 * Checks that an acceptable order of elaboration exists for the program
6338 and issues an error message if it cannot find an order of elaboration
6339 that satisfies the rules in Chapter 10 of the Ada Language Manual.
6341 * Generates a main program incorporating the given elaboration order.
6342 This program is a small Ada package (body and spec) that
6343 must be subsequently compiled
6344 using the GNAT compiler. The necessary compilation step is usually
6345 performed automatically by ``gnatlink``. The two most important
6346 functions of this program
6347 are to call the elaboration routines of units in an appropriate order
6348 and to call the main program.
6350 * Determines the set of object files required by the given main program.
6351 This information is output in the forms of comments in the generated program,
6352 to be read by the ``gnatlink`` utility used to link the Ada application.
6354 .. _Running_gnatbind:
6356 Running ``gnatbind``
6357 --------------------
6359 The form of the ``gnatbind`` command is
6363 $ gnatbind [ switches ] mainprog[.ali] [ switches ]
6366 where :file:`mainprog.adb` is the Ada file containing the main program
6367 unit body. ``gnatbind`` constructs an Ada
6368 package in two files whose names are
6369 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
6370 For example, if given the
6371 parameter :file:`hello.ali`, for a main program contained in file
6372 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
6373 and :file:`b~hello.adb`.
6375 When doing consistency checking, the binder takes into consideration
6376 any source files it can locate. For example, if the binder determines
6377 that the given main program requires the package ``Pack``, whose
6379 file is :file:`pack.ali` and whose corresponding source spec file is
6380 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
6381 (using the same search path conventions as previously described for the
6382 ``gcc`` command). If it can locate this source file, it checks that
6384 or source checksums of the source and its references to in :file:`ALI` files
6385 match. In other words, any :file:`ALI` files that mentions this spec must have
6386 resulted from compiling this version of the source file (or in the case
6387 where the source checksums match, a version close enough that the
6388 difference does not matter).
6390 .. index:: Source files, use by binder
6392 The effect of this consistency checking, which includes source files, is
6393 that the binder ensures that the program is consistent with the latest
6394 version of the source files that can be located at bind time. Editing a
6395 source file without compiling files that depend on the source file cause
6396 error messages to be generated by the binder.
6398 For example, suppose you have a main program :file:`hello.adb` and a
6399 package ``P``, from file :file:`p.ads` and you perform the following
6402 * Enter ``gcc -c hello.adb`` to compile the main program.
6404 * Enter ``gcc -c p.ads`` to compile package ``P``.
6406 * Edit file :file:`p.ads`.
6408 * Enter ``gnatbind hello``.
6410 At this point, the file :file:`p.ali` contains an out-of-date time stamp
6411 because the file :file:`p.ads` has been edited. The attempt at binding
6412 fails, and the binder generates the following error messages:
6417 error: "hello.adb" must be recompiled ("p.ads" has been modified)
6418 error: "p.ads" has been modified and must be recompiled
6421 Now both files must be recompiled as indicated, and then the bind can
6422 succeed, generating a main program. You need not normally be concerned
6423 with the contents of this file, but for reference purposes a sample
6424 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6426 In most normal usage, the default mode of ``gnatbind`` which is to
6427 generate the main package in Ada, as described in the previous section.
6428 In particular, this means that any Ada programmer can read and understand
6429 the generated main program. It can also be debugged just like any other
6430 Ada code provided the :switch:`-g` switch is used for
6431 ``gnatbind`` and ``gnatlink``.
6433 .. _Switches_for_gnatbind:
6435 Switches for ``gnatbind``
6436 -------------------------
6438 The following switches are available with ``gnatbind``; details will
6439 be presented in subsequent sections.
6442 .. index:: --version (gnatbind)
6445 Display Copyright and version, then exit disregarding all other options.
6448 .. index:: --help (gnatbind)
6451 If :switch:`--version` was not used, display usage, then exit disregarding
6455 .. index:: -a (gnatbind)
6458 Indicates that, if supported by the platform, the adainit procedure should
6459 be treated as an initialisation routine by the linker (a constructor). This
6460 is intended to be used by the Project Manager to automatically initialize
6461 shared Stand-Alone Libraries.
6464 .. index:: -aO (gnatbind)
6467 Specify directory to be searched for ALI files.
6470 .. index:: -aI (gnatbind)
6473 Specify directory to be searched for source file.
6476 .. index:: -A (gnatbind)
6478 :switch:`-A[={filename}]`
6479 Output ALI list (to standard output or to the named file).
6482 .. index:: -b (gnatbind)
6485 Generate brief messages to :file:`stderr` even if verbose mode set.
6488 .. index:: -c (gnatbind)
6491 Check only, no generation of binder output file.
6494 .. index:: -dnn[k|m] (gnatbind)
6496 :switch:`-d{nn}[k|m]`
6497 This switch can be used to change the default task stack size value
6498 to a specified size ``nn``, which is expressed in bytes by default, or
6499 in kilobytes when suffixed with ``k`` or in megabytes when suffixed
6501 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6502 in effect, to completing all task specs with
6506 pragma Storage_Size (nn);
6508 When they do not already have such a pragma.
6511 .. index:: -D (gnatbind)
6513 :switch:`-D{nn}[k|m]`
6514 Set the default secondary stack size to ``nn``. The suffix indicates whether
6515 the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
6518 The secondary stack holds objects of unconstrained types that are returned by
6519 functions, for example unconstrained Strings. The size of the secondary stack
6520 can be dynamic or fixed depending on the target.
6522 For most targets, the secondary stack grows on demand and is implemented as
6523 a chain of blocks in the heap. In this case, the default secondary stack size
6524 determines the initial size of the secondary stack for each task and the
6525 smallest amount the secondary stack can grow by.
6527 For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
6528 fixed. This switch can be used to change the default size of these stacks.
6529 The default secondary stack size can be overridden on a per-task basis if
6530 individual tasks have different secondary stack requirements. This is
6531 achieved through the Secondary_Stack_Size aspect that takes the size of the
6532 secondary stack in bytes.
6534 .. index:: -e (gnatbind)
6537 Output complete list of elaboration-order dependencies.
6540 .. index:: -Ea (gnatbind)
6543 Store tracebacks in exception occurrences when the target supports it.
6544 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6545 unless symbolic tracebacks are enabled.
6547 See also the packages ``GNAT.Traceback`` and
6548 ``GNAT.Traceback.Symbolic`` for more information.
6549 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
6553 .. index:: -Es (gnatbind)
6556 Store tracebacks in exception occurrences when the target supports it.
6557 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6560 .. index:: -E (gnatbind)
6563 Currently the same as ``-Ea``.
6566 .. index:: -f (gnatbind)
6568 :switch:`-f{elab-order}`
6569 Force elaboration order. For further details see :ref:`Elaboration_Control`
6570 and :ref:`Elaboration_Order_Handling_in_GNAT`.
6573 .. index:: -F (gnatbind)
6576 Force the checks of elaboration flags. ``gnatbind`` does not normally
6577 generate checks of elaboration flags for the main executable, except when
6578 a Stand-Alone Library is used. However, there are cases when this cannot be
6579 detected by gnatbind. An example is importing an interface of a Stand-Alone
6580 Library through a pragma Import and only specifying through a linker switch
6581 this Stand-Alone Library. This switch is used to guarantee that elaboration
6582 flag checks are generated.
6585 .. index:: -h (gnatbind)
6588 Output usage (help) information.
6591 .. index:: -H (gnatbind)
6594 Legacy elaboration order model enabled. For further details see
6595 :ref:`Elaboration_Order_Handling_in_GNAT`.
6598 .. index:: -H32 (gnatbind)
6601 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
6602 For further details see :ref:`Dynamic_Allocation_Control`.
6605 .. index:: -H64 (gnatbind)
6606 .. index:: __gnat_malloc
6609 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
6610 For further details see :ref:`Dynamic_Allocation_Control`.
6613 .. index:: -I (gnatbind)
6616 Specify directory to be searched for source and ALI files.
6619 .. index:: -I- (gnatbind)
6622 Do not look for sources in the current directory where ``gnatbind`` was
6623 invoked, and do not look for ALI files in the directory containing the
6624 ALI file named in the ``gnatbind`` command line.
6627 .. index:: -k (gnatbind)
6630 Disable checking of elaboration flags. When using :switch:`-n`
6631 either explicitly or implicitly, :switch:`-F` is also implied,
6632 unless :switch:`-k` is used. This switch should be used with care
6633 and you should ensure manually that elaboration routines are not called
6634 twice unintentionally.
6637 .. index:: -K (gnatbind)
6640 Give list of linker options specified for link.
6643 .. index:: -l (gnatbind)
6646 Output chosen elaboration order.
6649 .. index:: -L (gnatbind)
6652 Bind the units for library building. In this case the ``adainit`` and
6653 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6654 are renamed to :samp:`{xxx}init` and
6657 (:ref:`GNAT_and_Libraries`, for more details.)
6660 .. index:: -M (gnatbind)
6663 Rename generated main program from main to xyz. This option is
6664 supported on cross environments only.
6666 .. index:: -m (gnatbind)
6669 Limit number of detected errors or warnings to ``n``, where ``n`` is
6670 in the range 1..999999. The default value if no switch is
6671 given is 9999. If the number of warnings reaches this limit, then a
6672 message is output and further warnings are suppressed, the bind
6673 continues in this case. If the number of errors reaches this
6674 limit, then a message is output and the bind is abandoned.
6675 A value of zero means that no limit is enforced. The equal
6678 .. index:: -minimal (gnatbind)
6681 Generate a binder file suitable for space-constrained applications. When
6682 active, binder-generated objects not required for program operation are no
6683 longer generated. **Warning:** this option comes with the following
6686 * Starting the program's execution in the debugger will cause it to
6687 stop at the start of the ``main`` function instead of the main subprogram.
6688 This can be worked around by manually inserting a breakpoint on that
6689 subprogram and resuming the program's execution until reaching that breakpoint.
6690 * Programs using GNAT.Compiler_Version will not link.
6692 .. index:: -n (gnatbind)
6698 .. index:: -nostdinc (gnatbind)
6701 Do not look for sources in the system default directory.
6704 .. index:: -nostdlib (gnatbind)
6707 Do not look for library files in the system default directory.
6710 .. index:: --RTS (gnatbind)
6712 :switch:`--RTS={rts-path}`
6713 Specifies the default location of the run-time library. Same meaning as the
6714 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
6716 .. index:: -o (gnatbind)
6719 Name the output file ``file`` (default is :file:`b~`xxx`.adb`).
6720 Note that if this option is used, then linking must be done manually,
6721 gnatlink cannot be used.
6724 .. index:: -O (gnatbind)
6726 :switch:`-O[={filename}]`
6727 Output object list (to standard output or to the named file).
6730 .. index:: -p (gnatbind)
6733 Pessimistic (worst-case) elaboration order.
6736 .. index:: -P (gnatbind)
6739 Generate binder file suitable for CodePeer.
6742 .. index:: -R (gnatbind)
6745 Output closure source list, which includes all non-run-time units that are
6746 included in the bind.
6749 .. index:: -Ra (gnatbind)
6752 Like :switch:`-R` but the list includes run-time units.
6755 .. index:: -s (gnatbind)
6758 Require all source files to be present.
6761 .. index:: -S (gnatbind)
6764 Specifies the value to be used when detecting uninitialized scalar
6765 objects with pragma Initialize_Scalars.
6766 The ``xxx`` string specified with the switch is one of:
6768 * ``in`` for an invalid value.
6770 If zero is invalid for the discrete type in question,
6771 then the scalar value is set to all zero bits.
6772 For signed discrete types, the largest possible negative value of
6773 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6774 For unsigned discrete types, the underlying scalar value is set to all
6775 one bits. For floating-point types, a NaN value is set
6776 (see body of package System.Scalar_Values for exact values).
6778 * ``lo`` for low value.
6780 If zero is invalid for the discrete type in question,
6781 then the scalar value is set to all zero bits.
6782 For signed discrete types, the largest possible negative value of
6783 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6784 For unsigned discrete types, the underlying scalar value is set to all
6785 zero bits. For floating-point, a small value is set
6786 (see body of package System.Scalar_Values for exact values).
6788 * ``hi`` for high value.
6790 If zero is invalid for the discrete type in question,
6791 then the scalar value is set to all one bits.
6792 For signed discrete types, the largest possible positive value of
6793 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6794 For unsigned discrete types, the underlying scalar value is set to all
6795 one bits. For floating-point, a large value is set
6796 (see body of package System.Scalar_Values for exact values).
6798 * ``xx`` for hex value (two hex digits).
6800 The underlying scalar is set to a value consisting of repeated bytes, whose
6801 value corresponds to the given value. For example if ``BF`` is given,
6802 then a 32-bit scalar value will be set to the bit pattern ``16#BFBFBFBF#``.
6804 .. index:: GNAT_INIT_SCALARS
6806 In addition, you can specify :switch:`-Sev` to indicate that the value is
6807 to be set at run time. In this case, the program will look for an environment
6808 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
6809 of :samp:`in/lo/hi/{xx}` with the same meanings as above.
6810 If no environment variable is found, or if it does not have a valid value,
6811 then the default is ``in`` (invalid values).
6813 .. index:: -static (gnatbind)
6816 Link against a static GNAT run-time.
6819 .. index:: -shared (gnatbind)
6822 Link against a shared GNAT run-time when available.
6825 .. index:: -t (gnatbind)
6828 Tolerate time stamp and other consistency errors.
6831 .. index:: -T (gnatbind)
6834 Set the time slice value to ``n`` milliseconds. If the system supports
6835 the specification of a specific time slice value, then the indicated value
6836 is used. If the system does not support specific time slice values, but
6837 does support some general notion of round-robin scheduling, then any
6838 nonzero value will activate round-robin scheduling.
6840 A value of zero is treated specially. It turns off time
6841 slicing, and in addition, indicates to the tasking run-time that the
6842 semantics should match as closely as possible the Annex D
6843 requirements of the Ada RM, and in particular sets the default
6844 scheduling policy to ``FIFO_Within_Priorities``.
6847 .. index:: -u (gnatbind)
6850 Enable dynamic stack usage, with ``n`` results stored and displayed
6851 at program termination. A result is generated when a task
6852 terminates. Results that can't be stored are displayed on the fly, at
6853 task termination. This option is currently not supported on Itanium
6854 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6857 .. index:: -v (gnatbind)
6860 Verbose mode. Write error messages, header, summary output to
6864 .. index:: -V (gnatbind)
6866 :switch:`-V{key}={value}`
6867 Store the given association of ``key`` to ``value`` in the bind environment.
6868 Values stored this way can be retrieved at run time using
6869 ``GNAT.Bind_Environment``.
6872 .. index:: -w (gnatbind)
6875 Warning mode; ``x`` = s/e for suppress/treat as error.
6878 .. index:: -Wx (gnatbind)
6881 Override default wide character encoding for standard Text_IO files.
6884 .. index:: -x (gnatbind)
6887 Exclude source files (check object consistency only).
6890 .. index:: -xdr (gnatbind)
6893 Use the target-independent XDR protocol for stream oriented attributes
6894 instead of the default implementation which is based on direct binary
6895 representations and is therefore target-and endianness-dependent.
6896 However it does not support 128-bit integer types and the exception
6897 ``Ada.IO_Exceptions.Device_Error`` is raised if any attempt is made
6898 at streaming 128-bit integer types with it.
6901 .. index:: -Xnnn (gnatbind)
6904 Set default exit status value, normally 0 for POSIX compliance.
6907 .. index:: -y (gnatbind)
6910 Enable leap seconds support in ``Ada.Calendar`` and its children.
6913 .. index:: -z (gnatbind)
6918 You may obtain this listing of switches by running ``gnatbind`` with
6922 .. _Consistency-Checking_Modes:
6924 Consistency-Checking Modes
6925 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6927 As described earlier, by default ``gnatbind`` checks
6928 that object files are consistent with one another and are consistent
6929 with any source files it can locate. The following switches control binder
6933 .. index:: -s (gnatbind)
6936 Require source files to be present. In this mode, the binder must be
6937 able to locate all source files that are referenced, in order to check
6938 their consistency. In normal mode, if a source file cannot be located it
6939 is simply ignored. If you specify this switch, a missing source
6943 .. index:: -Wx (gnatbind)
6946 Override default wide character encoding for standard Text_IO files.
6947 Normally the default wide character encoding method used for standard
6948 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6949 the main source input (see description of switch
6950 :switch:`-gnatWx` for the compiler). The
6951 use of this switch for the binder (which has the same set of
6952 possible arguments) overrides this default as specified.
6955 .. index:: -x (gnatbind)
6958 Exclude source files. In this mode, the binder only checks that ALI
6959 files are consistent with one another. Source files are not accessed.
6960 The binder runs faster in this mode, and there is still a guarantee that
6961 the resulting program is self-consistent.
6962 If a source file has been edited since it was last compiled, and you
6963 specify this switch, the binder will not detect that the object
6964 file is out of date with respect to the source file. Note that this is the
6965 mode that is automatically used by ``gnatmake`` because in this
6966 case the checking against sources has already been performed by
6967 ``gnatmake`` in the course of compilation (i.e., before binding).
6970 .. _Binder_Error_Message_Control:
6972 Binder Error Message Control
6973 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6975 The following switches provide control over the generation of error
6976 messages from the binder:
6980 .. index:: -v (gnatbind)
6983 Verbose mode. In the normal mode, brief error messages are generated to
6984 :file:`stderr`. If this switch is present, a header is written
6985 to :file:`stdout` and any error messages are directed to :file:`stdout`.
6986 All that is written to :file:`stderr` is a brief summary message.
6989 .. index:: -b (gnatbind)
6992 Generate brief error messages to :file:`stderr` even if verbose mode is
6993 specified. This is relevant only when used with the
6994 :switch:`-v` switch.
6997 .. index:: -m (gnatbind)
7000 Limits the number of error messages to ``n``, a decimal integer in the
7001 range 1-999. The binder terminates immediately if this limit is reached.
7004 .. index:: -M (gnatbind)
7007 Renames the generated main program from ``main`` to ``xxx``.
7008 This is useful in the case of some cross-building environments, where
7009 the actual main program is separate from the one generated
7013 .. index:: -ws (gnatbind)
7017 Suppress all warning messages.
7020 .. index:: -we (gnatbind)
7023 Treat any warning messages as fatal errors.
7026 .. index:: -t (gnatbind)
7027 .. index:: Time stamp checks, in binder
7028 .. index:: Binder consistency checks
7029 .. index:: Consistency checks, in binder
7032 The binder performs a number of consistency checks including:
7035 * Check that time stamps of a given source unit are consistent
7037 * Check that checksums of a given source unit are consistent
7039 * Check that consistent versions of ``GNAT`` were used for compilation
7041 * Check consistency of configuration pragmas as required
7043 Normally failure of such checks, in accordance with the consistency
7044 requirements of the Ada Reference Manual, causes error messages to be
7045 generated which abort the binder and prevent the output of a binder
7046 file and subsequent link to obtain an executable.
7048 The :switch:`-t` switch converts these error messages
7049 into warnings, so that
7050 binding and linking can continue to completion even in the presence of such
7051 errors. The result may be a failed link (due to missing symbols), or a
7052 non-functional executable which has undefined semantics.
7056 This means that :switch:`-t` should be used only in unusual situations,
7059 .. _Elaboration_Control:
7064 The following switches provide additional control over the elaboration
7065 order. For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
7068 .. index:: -f (gnatbind)
7070 :switch:`-f{elab-order}`
7071 Force elaboration order.
7073 ``elab-order`` should be the name of a "forced elaboration order file", that
7074 is, a text file containing library item names, one per line. A name of the
7075 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
7076 name of the form "some.unit%b" or "some.unit (body)" denotes the body of
7077 Some.Unit. Each pair of lines is taken to mean that there is an elaboration
7078 dependence of the second line on the first. For example, if the file
7088 then the spec of This will be elaborated before the body of This, and the
7089 body of This will be elaborated before the spec of That, and the spec of That
7090 will be elaborated before the body of That. The first and last of these three
7091 dependences are already required by Ada rules, so this file is really just
7092 forcing the body of This to be elaborated before the spec of That.
7094 The given order must be consistent with Ada rules, or else ``gnatbind`` will
7095 give elaboration cycle errors. For example, if you say x (body) should be
7096 elaborated before x (spec), there will be a cycle, because Ada rules require
7097 x (spec) to be elaborated before x (body); you can't have the spec and body
7098 both elaborated before each other.
7100 If you later add "with That;" to the body of This, there will be a cycle, in
7101 which case you should erase either "this (body)" or "that (spec)" from the
7102 above forced elaboration order file.
7104 Blank lines and Ada-style comments are ignored. Unit names that do not exist
7105 in the program are ignored. Units in the GNAT predefined library are also
7109 .. index:: -p (gnatbind)
7112 Pessimistic elaboration order
7114 This switch is only applicable to the pre-20.x legacy elaboration models.
7115 The post-20.x elaboration model uses a more informed approach of ordering
7118 Normally the binder attempts to choose an elaboration order that is likely to
7119 minimize the likelihood of an elaboration order error resulting in raising a
7120 ``Program_Error`` exception. This switch reverses the action of the binder,
7121 and requests that it deliberately choose an order that is likely to maximize
7122 the likelihood of an elaboration error. This is useful in ensuring
7123 portability and avoiding dependence on accidental fortuitous elaboration
7126 Normally it only makes sense to use the :switch:`-p` switch if dynamic
7127 elaboration checking is used (:switch:`-gnatE` switch used for compilation).
7128 This is because in the default static elaboration mode, all necessary
7129 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
7130 These implicit pragmas are still respected by the binder in :switch:`-p`
7131 mode, so a safe elaboration order is assured.
7133 Note that :switch:`-p` is not intended for production use; it is more for
7134 debugging/experimental use.
7141 The following switches allow additional control over the output
7142 generated by the binder.
7145 .. index:: -c (gnatbind)
7148 Check only. Do not generate the binder output file. In this mode the
7149 binder performs all error checks but does not generate an output file.
7152 .. index:: -e (gnatbind)
7155 Output complete list of elaboration-order dependencies, showing the
7156 reason for each dependency. This output can be rather extensive but may
7157 be useful in diagnosing problems with elaboration order. The output is
7158 written to :file:`stdout`.
7161 .. index:: -h (gnatbind)
7164 Output usage information. The output is written to :file:`stdout`.
7167 .. index:: -K (gnatbind)
7170 Output linker options to :file:`stdout`. Includes library search paths,
7171 contents of pragmas Ident and Linker_Options, and libraries added
7175 .. index:: -l (gnatbind)
7178 Output chosen elaboration order. The output is written to :file:`stdout`.
7181 .. index:: -O (gnatbind)
7184 Output full names of all the object files that must be linked to provide
7185 the Ada component of the program. The output is written to :file:`stdout`.
7186 This list includes the files explicitly supplied and referenced by the user
7187 as well as implicitly referenced run-time unit files. The latter are
7188 omitted if the corresponding units reside in shared libraries. The
7189 directory names for the run-time units depend on the system configuration.
7192 .. index:: -o (gnatbind)
7195 Set name of output file to ``file`` instead of the normal
7196 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
7197 binder generated body filename.
7198 Note that if this option is used, then linking must be done manually.
7199 It is not possible to use gnatlink in this case, since it cannot locate
7203 .. index:: -r (gnatbind)
7206 Generate list of ``pragma Restrictions`` that could be applied to
7207 the current unit. This is useful for code audit purposes, and also may
7208 be used to improve code generation in some cases.
7211 .. _Dynamic_Allocation_Control:
7213 Dynamic Allocation Control
7214 ^^^^^^^^^^^^^^^^^^^^^^^^^^
7216 The heap control switches -- :switch:`-H32` and :switch:`-H64` --
7217 determine whether dynamic allocation uses 32-bit or 64-bit memory.
7218 They only affect compiler-generated allocations via ``__gnat_malloc``;
7219 explicit calls to ``malloc`` and related functions from the C
7220 run-time library are unaffected.
7223 Allocate memory on 32-bit heap
7227 Allocate memory on 64-bit heap. This is the default
7228 unless explicitly overridden by a ``'Size`` clause on the access type.
7230 These switches are only effective on VMS platforms.
7233 .. _Binding_with_Non-Ada_Main_Programs:
7235 Binding with Non-Ada Main Programs
7236 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7238 The description so far has assumed that the main
7239 program is in Ada, and that the task of the binder is to generate a
7240 corresponding function ``main`` that invokes this Ada main
7241 program. GNAT also supports the building of executable programs where
7242 the main program is not in Ada, but some of the called routines are
7243 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
7244 The following switch is used in this situation:
7247 .. index:: -n (gnatbind)
7250 No main program. The main program is not in Ada.
7252 In this case, most of the functions of the binder are still required,
7253 but instead of generating a main program, the binder generates a file
7254 containing the following callable routines:
7259 You must call this routine to initialize the Ada part of the program by
7260 calling the necessary elaboration routines. A call to ``adainit`` is
7261 required before the first call to an Ada subprogram.
7263 Note that it is assumed that the basic execution environment must be setup
7264 to be appropriate for Ada execution at the point where the first Ada
7265 subprogram is called. In particular, if the Ada code will do any
7266 floating-point operations, then the FPU must be setup in an appropriate
7267 manner. For the case of the x86, for example, full precision mode is
7268 required. The procedure GNAT.Float_Control.Reset may be used to ensure
7269 that the FPU is in the right state.
7274 You must call this routine to perform any library-level finalization
7275 required by the Ada subprograms. A call to ``adafinal`` is required
7276 after the last call to an Ada subprogram, and before the program
7279 .. index:: -n (gnatbind)
7280 .. index:: Binder, multiple input files
7282 If the :switch:`-n` switch
7283 is given, more than one ALI file may appear on
7284 the command line for ``gnatbind``. The normal ``closure``
7285 calculation is performed for each of the specified units. Calculating
7286 the closure means finding out the set of units involved by tracing
7287 |with| references. The reason it is necessary to be able to
7288 specify more than one ALI file is that a given program may invoke two or
7289 more quite separate groups of Ada units.
7291 The binder takes the name of its output file from the last specified ALI
7292 file, unless overridden by the use of the :switch:`-o file`.
7294 .. index:: -o (gnatbind)
7296 The output is an Ada unit in source form that can be compiled with GNAT.
7297 This compilation occurs automatically as part of the ``gnatlink``
7300 Currently the GNAT run-time requires a FPU using 80 bits mode
7301 precision. Under targets where this is not the default it is required to
7302 call GNAT.Float_Control.Reset before using floating point numbers (this
7303 include float computation, float input and output) in the Ada code. A
7304 side effect is that this could be the wrong mode for the foreign code
7305 where floating point computation could be broken after this call.
7308 .. _Binding_Programs_with_No_Main_Subprogram:
7310 Binding Programs with No Main Subprogram
7311 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7313 It is possible to have an Ada program which does not have a main
7314 subprogram. This program will call the elaboration routines of all the
7315 packages, then the finalization routines.
7317 The following switch is used to bind programs organized in this manner:
7319 .. index:: -z (gnatbind)
7322 Normally the binder checks that the unit name given on the command line
7323 corresponds to a suitable main subprogram. When this switch is used,
7324 a list of ALI files can be given, and the execution of the program
7325 consists of elaboration of these units in an appropriate order. Note
7326 that the default wide character encoding method for standard Text_IO
7327 files is always set to Brackets if this switch is set (you can use
7329 :switch:`-Wx` to override this default).
7332 .. _Command-Line_Access:
7337 The package ``Ada.Command_Line`` provides access to the command-line
7338 arguments and program name. In order for this interface to operate
7339 correctly, the two variables
7346 .. index:: gnat_argv
7347 .. index:: gnat_argc
7349 are declared in one of the GNAT library routines. These variables must
7350 be set from the actual ``argc`` and ``argv`` values passed to the
7351 main program. With no *n* present, ``gnatbind``
7352 generates the C main program to automatically set these variables.
7353 If the *n* switch is used, there is no automatic way to
7354 set these variables. If they are not set, the procedures in
7355 ``Ada.Command_Line`` will not be available, and any attempt to use
7356 them will raise ``Constraint_Error``. If command line access is
7357 required, your main program must set ``gnat_argc`` and
7358 ``gnat_argv`` from the ``argc`` and ``argv`` values passed to
7362 .. _Search_Paths_for_gnatbind:
7364 Search Paths for ``gnatbind``
7365 -----------------------------
7367 The binder takes the name of an ALI file as its argument and needs to
7368 locate source files as well as other ALI files to verify object consistency.
7370 For source files, it follows exactly the same search rules as ``gcc``
7371 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
7372 directories searched are:
7374 * The directory containing the ALI file named in the command line, unless
7375 the switch :switch:`-I-` is specified.
7377 * All directories specified by :switch:`-I`
7378 switches on the ``gnatbind``
7379 command line, in the order given.
7381 .. index:: ADA_PRJ_OBJECTS_FILE
7383 * Each of the directories listed in the text file whose name is given
7384 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
7386 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
7387 driver when project files are used. It should not normally be set
7390 .. index:: ADA_OBJECTS_PATH
7392 * Each of the directories listed in the value of the
7393 :envvar:`ADA_OBJECTS_PATH` environment variable.
7394 Construct this value
7395 exactly as the :envvar:`PATH` environment variable: a list of directory
7396 names separated by colons (semicolons when working with the NT version
7399 * The content of the :file:`ada_object_path` file which is part of the GNAT
7400 installation tree and is used to store standard libraries such as the
7401 GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
7402 specified. See :ref:`Installing_a_library`
7404 .. index:: -I (gnatbind)
7405 .. index:: -aI (gnatbind)
7406 .. index:: -aO (gnatbind)
7408 In the binder the switch :switch:`-I`
7409 is used to specify both source and
7410 library file paths. Use :switch:`-aI`
7411 instead if you want to specify
7412 source paths only, and :switch:`-aO`
7413 if you want to specify library paths
7414 only. This means that for the binder
7415 :switch:`-I{dir}` is equivalent to
7417 :switch:`-aO`{dir}`.
7418 The binder generates the bind file (a C language source file) in the
7419 current working directory.
7423 .. index:: Interfaces
7426 The packages ``Ada``, ``System``, and ``Interfaces`` and their
7427 children make up the GNAT Run-Time Library, together with the package
7428 GNAT and its children, which contain a set of useful additional
7429 library functions provided by GNAT. The sources for these units are
7430 needed by the compiler and are kept together in one directory. The ALI
7431 files and object files generated by compiling the RTL are needed by the
7432 binder and the linker and are kept together in one directory, typically
7433 different from the directory containing the sources. In a normal
7434 installation, you need not specify these directory names when compiling
7435 or binding. Either the environment variables or the built-in defaults
7436 cause these files to be found.
7438 Besides simplifying access to the RTL, a major use of search paths is
7439 in compiling sources from multiple directories. This can make
7440 development environments much more flexible.
7443 .. _Examples_of_gnatbind_Usage:
7445 Examples of ``gnatbind`` Usage
7446 ------------------------------
7448 Here are some examples of ``gnatbind`` invocations:
7454 The main program ``Hello`` (source program in :file:`hello.adb`) is
7455 bound using the standard switch settings. The generated main program is
7456 :file:`b~hello.adb`. This is the normal, default use of the binder.
7460 gnatbind hello -o mainprog.adb
7462 The main program ``Hello`` (source program in :file:`hello.adb`) is
7463 bound using the standard switch settings. The generated main program is
7464 :file:`mainprog.adb` with the associated spec in
7465 :file:`mainprog.ads`. Note that you must specify the body here not the
7466 spec. Note that if this option is used, then linking must be done manually,
7467 since gnatlink will not be able to find the generated file.
7470 .. _Linking_with_gnatlink:
7472 Linking with ``gnatlink``
7473 =========================
7475 .. index:: ! gnatlink
7477 This chapter discusses ``gnatlink``, a tool that links
7478 an Ada program and builds an executable file. This utility
7479 invokes the system linker (via the ``gcc`` command)
7480 with a correct list of object files and library references.
7481 ``gnatlink`` automatically determines the list of files and
7482 references for the Ada part of a program. It uses the binder file
7483 generated by the ``gnatbind`` to determine this list.
7485 .. _Running_gnatlink:
7487 Running ``gnatlink``
7488 --------------------
7490 The form of the ``gnatlink`` command is
7495 $ gnatlink [ switches ] mainprog [.ali]
7496 [ non-Ada objects ] [ linker options ]
7500 The arguments of ``gnatlink`` (switches, main ``ALI`` file,
7502 or linker options) may be in any order, provided that no non-Ada object may
7503 be mistaken for a main :file:`ALI` file.
7504 Any file name :file:`F` without the :file:`.ali`
7505 extension will be taken as the main :file:`ALI` file if a file exists
7506 whose name is the concatenation of :file:`F` and :file:`.ali`.
7508 :file:`mainprog.ali` references the ALI file of the main program.
7509 The :file:`.ali` extension of this file can be omitted. From this
7510 reference, ``gnatlink`` locates the corresponding binder file
7511 :file:`b~mainprog.adb` and, using the information in this file along
7512 with the list of non-Ada objects and linker options, constructs a
7513 linker command file to create the executable.
7515 The arguments other than the ``gnatlink`` switches and the main
7516 :file:`ALI` file are passed to the linker uninterpreted.
7517 They typically include the names of
7518 object files for units written in other languages than Ada and any library
7519 references required to resolve references in any of these foreign language
7520 units, or in ``Import`` pragmas in any Ada units.
7522 ``linker options`` is an optional list of linker specific
7524 The default linker called by gnatlink is ``gcc`` which in
7525 turn calls the appropriate system linker.
7527 One useful option for the linker is :switch:`-s`: it reduces the size of the
7528 executable by removing all symbol table and relocation information from the
7531 Standard options for the linker such as :switch:`-lmy_lib` or
7532 :switch:`-Ldir` can be added as is.
7533 For options that are not recognized by
7534 ``gcc`` as linker options, use the ``gcc`` switches
7535 :switch:`-Xlinker` or :switch:`-Wl,`.
7537 Refer to the GCC documentation for
7540 Here is an example showing how to generate a linker map:
7544 $ gnatlink my_prog -Wl,-Map,MAPFILE
7547 Using ``linker options`` it is possible to set the program stack and
7549 See :ref:`Setting_Stack_Size_from_gnatlink` and
7550 :ref:`Setting_Heap_Size_from_gnatlink`.
7552 ``gnatlink`` determines the list of objects required by the Ada
7553 program and prepends them to the list of objects passed to the linker.
7554 ``gnatlink`` also gathers any arguments set by the use of
7555 ``pragma Linker_Options`` and adds them to the list of arguments
7556 presented to the linker.
7559 .. _Switches_for_gnatlink:
7561 Switches for ``gnatlink``
7562 -------------------------
7564 The following switches are available with the ``gnatlink`` utility:
7566 .. index:: --version (gnatlink)
7569 Display Copyright and version, then exit disregarding all other options.
7572 .. index:: --help (gnatlink)
7575 If :switch:`--version` was not used, display usage, then exit disregarding
7579 .. index:: Command line length
7580 .. index:: -f (gnatlink)
7583 On some targets, the command line length is limited, and ``gnatlink``
7584 will generate a separate file for the linker if the list of object files
7586 The :switch:`-f` switch forces this file
7587 to be generated even if
7588 the limit is not exceeded. This is useful in some cases to deal with
7589 special situations where the command line length is exceeded.
7592 .. index:: Debugging information, including
7593 .. index:: -g (gnatlink)
7596 The option to include debugging information causes the Ada bind file (in
7597 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
7598 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7599 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7600 Without :switch:`-g`, the binder removes these files by default.
7602 .. index:: -n (gnatlink)
7605 Do not compile the file generated by the binder. This may be used when
7606 a link is rerun with different options, but there is no need to recompile
7610 .. index:: -v (gnatlink)
7613 Verbose mode. Causes additional information to be output, including a full
7614 list of the included object files.
7615 This switch option is most useful when you want
7616 to see what set of object files are being used in the link step.
7619 .. index:: -v -v (gnatlink)
7622 Very verbose mode. Requests that the compiler operate in verbose mode when
7623 it compiles the binder file, and that the system linker run in verbose mode.
7626 .. index:: -o (gnatlink)
7628 :switch:`-o {exec-name}`
7629 ``exec-name`` specifies an alternate name for the generated
7630 executable program. If this switch is omitted, the executable has the same
7631 name as the main unit. For example, ``gnatlink try.ali`` creates
7632 an executable called :file:`try`.
7635 .. index:: -B (gnatlink)
7638 Load compiler executables (for example, ``gnat1``, the Ada compiler)
7639 from ``dir`` instead of the default location. Only use this switch
7640 when multiple versions of the GNAT compiler are available.
7641 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
7642 for further details. You would normally use the :switch:`-b` or
7643 :switch:`-V` switch instead.
7646 .. index:: -M (gnatlink)
7649 When linking an executable, create a map file. The name of the map file
7650 has the same name as the executable with extension ".map".
7653 .. index:: -M= (gnatlink)
7655 :switch:`-M={mapfile}`
7656 When linking an executable, create a map file. The name of the map file is
7660 .. index:: --GCC=compiler_name (gnatlink)
7662 :switch:`--GCC={compiler_name}`
7663 Program used for compiling the binder file. The default is
7664 ``gcc``. You need to use quotes around ``compiler_name`` if
7665 ``compiler_name`` contains spaces or other separator characters.
7666 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
7667 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7668 inserted after your command name. Thus in the above example the compiler
7669 command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
7670 A limitation of this syntax is that the name and path name of the executable
7671 itself must not include any embedded spaces. If the compiler executable is
7672 different from the default one (gcc or <prefix>-gcc), then the back-end
7673 switches in the ALI file are not used to compile the binder generated source.
7674 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7675 switches will be used for ``--GCC="gcc -gnatv"``. If several
7676 ``--GCC=compiler_name`` are used, only the last ``compiler_name``
7677 is taken into account. However, all the additional switches are also taken
7679 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7680 ``--GCC="bar -x -y -z -t"``.
7683 .. index:: --LINK= (gnatlink)
7685 :switch:`--LINK={name}`
7686 ``name`` is the name of the linker to be invoked. This is especially
7687 useful in mixed language programs since languages such as C++ require
7688 their own linker to be used. When this switch is omitted, the default
7689 name for the linker is ``gcc``. When this switch is used, the
7690 specified linker is called instead of ``gcc`` with exactly the same
7691 parameters that would have been passed to ``gcc`` so if the desired
7692 linker requires different parameters it is necessary to use a wrapper
7693 script that massages the parameters before invoking the real linker. It
7694 may be useful to control the exact invocation by using the verbose
7698 .. _Using_the_GNU_make_Utility:
7700 Using the GNU ``make`` Utility
7701 ==============================
7703 .. index:: make (GNU), GNU make
7705 This chapter offers some examples of makefiles that solve specific
7706 problems. It does not explain how to write a makefile, nor does it try to replace the
7707 ``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7709 All the examples in this section are specific to the GNU version of
7710 make. Although ``make`` is a standard utility, and the basic language
7711 is the same, these examples use some advanced features found only in
7714 .. _Using_gnatmake_in_a_Makefile:
7716 Using gnatmake in a Makefile
7717 ----------------------------
7719 .. index makefile (GNU make)
7721 Complex project organizations can be handled in a very powerful way by
7722 using GNU make combined with gnatmake. For instance, here is a Makefile
7723 which allows you to build each subsystem of a big project into a separate
7724 shared library. Such a makefile allows you to significantly reduce the link
7725 time of very big applications while maintaining full coherence at
7726 each step of the build process.
7728 The list of dependencies are handled automatically by
7729 ``gnatmake``. The Makefile is simply used to call gnatmake in each of
7730 the appropriate directories.
7732 Note that you should also read the example on how to automatically
7733 create the list of directories
7734 (:ref:`Automatically_Creating_a_List_of_Directories`)
7735 which might help you in case your project has a lot of subdirectories.
7738 .. code-block:: makefile
7740 ## This Makefile is intended to be used with the following directory
7742 ## - The sources are split into a series of csc (computer software components)
7743 ## Each of these csc is put in its own directory.
7744 ## Their name are referenced by the directory names.
7745 ## They will be compiled into shared library (although this would also work
7746 ## with static libraries)
7747 ## - The main program (and possibly other packages that do not belong to any
7748 ## csc) is put in the top level directory (where the Makefile is).
7749 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7750 ## \\_ second_csc (sources) __ lib (will contain the library)
7752 ## Although this Makefile is build for shared library, it is easy to modify
7753 ## to build partial link objects instead (modify the lines with -shared and
7756 ## With this makefile, you can change any file in the system or add any new
7757 ## file, and everything will be recompiled correctly (only the relevant shared
7758 ## objects will be recompiled, and the main program will be re-linked).
7760 # The list of computer software component for your project. This might be
7761 # generated automatically.
7764 # Name of the main program (no extension)
7767 # If we need to build objects with -fPIC, uncomment the following line
7770 # The following variable should give the directory containing libgnat.so
7771 # You can get this directory through 'gnatls -v'. This is usually the last
7772 # directory in the Object_Path.
7775 # The directories for the libraries
7776 # (This macro expands the list of CSC to the list of shared libraries, you
7777 # could simply use the expanded form:
7778 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7779 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7781 ${MAIN}: objects ${LIB_DIR}
7782 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7783 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7786 # recompile the sources
7787 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7789 # Note: In a future version of GNAT, the following commands will be simplified
7790 # by a new tool, gnatmlib
7793 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7794 cd ${dir $@ } && cp -f ../*.ali .
7796 # The dependencies for the modules
7797 # Note that we have to force the expansion of *.o, since in some cases
7798 # make won't be able to do it itself.
7799 aa/lib/libaa.so: ${wildcard aa/*.o}
7800 bb/lib/libbb.so: ${wildcard bb/*.o}
7801 cc/lib/libcc.so: ${wildcard cc/*.o}
7803 # Make sure all of the shared libraries are in the path before starting the
7806 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7809 ${RM} -rf ${CSC_LIST:%=%/lib}
7810 ${RM} ${CSC_LIST:%=%/*.ali}
7811 ${RM} ${CSC_LIST:%=%/*.o}
7812 ${RM} *.o *.ali ${MAIN}
7815 .. _Automatically_Creating_a_List_of_Directories:
7817 Automatically Creating a List of Directories
7818 --------------------------------------------
7820 In most makefiles, you will have to specify a list of directories, and
7821 store it in a variable. For small projects, it is often easier to
7822 specify each of them by hand, since you then have full control over what
7823 is the proper order for these directories, which ones should be
7826 However, in larger projects, which might involve hundreds of
7827 subdirectories, it might be more convenient to generate this list
7830 The example below presents two methods. The first one, although less
7831 general, gives you more control over the list. It involves wildcard
7832 characters, that are automatically expanded by ``make``. Its
7833 shortcoming is that you need to explicitly specify some of the
7834 organization of your project, such as for instance the directory tree
7835 depth, whether some directories are found in a separate tree, etc.
7837 The second method is the most general one. It requires an external
7838 program, called ``find``, which is standard on all Unix systems. All
7839 the directories found under a given root directory will be added to the
7842 .. code-block:: makefile
7844 # The examples below are based on the following directory hierarchy:
7845 # All the directories can contain any number of files
7846 # ROOT_DIRECTORY -> a -> aa -> aaa
7852 # This Makefile creates a variable called DIRS, that can be reused any time
7853 # you need this list (see the other examples in this section)
7855 # The root of your project's directory hierarchy
7859 # First method: specify explicitly the list of directories
7860 # This allows you to specify any subset of all the directories you need.
7863 DIRS := a/aa/ a/ab/ b/ba/
7866 # Second method: use wildcards
7867 # Note that the argument(s) to wildcard below should end with a '/'.
7868 # Since wildcards also return file names, we have to filter them out
7869 # to avoid duplicate directory names.
7870 # We thus use make's ``dir`` and ``sort`` functions.
7871 # It sets DIRs to the following value (note that the directories aaa and baa
7872 # are not given, unless you change the arguments to wildcard).
7873 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7876 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7877 ${ROOT_DIRECTORY}/*/*/}}}
7880 # Third method: use an external program
7881 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7882 # This is the most complete command: it sets DIRs to the following value:
7883 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7886 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7890 .. _Generating_the_Command_Line_Switches:
7892 Generating the Command Line Switches
7893 ------------------------------------
7895 Once you have created the list of directories as explained in the
7896 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7897 you can easily generate the command line arguments to pass to gnatmake.
7899 For the sake of completeness, this example assumes that the source path
7900 is not the same as the object path, and that you have two separate lists
7903 .. code-block:: makefile
7905 # see "Automatically creating a list of directories" to create
7910 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7911 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7914 gnatmake ${GNATMAKE_SWITCHES} main_unit
7917 .. _Overcoming_Command_Line_Length_Limits:
7919 Overcoming Command Line Length Limits
7920 -------------------------------------
7922 One problem that might be encountered on big projects is that many
7923 operating systems limit the length of the command line. It is thus hard to give
7924 gnatmake the list of source and object directories.
7926 This example shows how you can set up environment variables, which will
7927 make ``gnatmake`` behave exactly as if the directories had been
7928 specified on the command line, but have a much higher length limit (or
7929 even none on most systems).
7931 It assumes that you have created a list of directories in your Makefile,
7932 using one of the methods presented in
7933 :ref:`Automatically_Creating_a_List_of_Directories`.
7934 For the sake of completeness, we assume that the object
7935 path (where the ALI files are found) is different from the sources patch.
7937 Note a small trick in the Makefile below: for efficiency reasons, we
7938 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7939 expanded immediately by ``make``. This way we overcome the standard
7940 make behavior which is to expand the variables only when they are
7943 On Windows, if you are using the standard Windows command shell, you must
7944 replace colons with semicolons in the assignments to these variables.
7946 .. code-block:: makefile
7948 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7949 # This is the same thing as putting the -I arguments on the command line.
7950 # (the equivalent of using -aI on the command line would be to define
7951 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
7952 # You can of course have different values for these variables.
7954 # Note also that we need to keep the previous values of these variables, since
7955 # they might have been set before running 'make' to specify where the GNAT
7956 # library is installed.
7958 # see "Automatically creating a list of directories" to create these
7964 space:=${empty} ${empty}
7965 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
7966 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
7967 ADA_INCLUDE_PATH += ${SOURCE_LIST}
7968 ADA_OBJECTS_PATH += ${OBJECT_LIST}
7969 export ADA_INCLUDE_PATH
7970 export ADA_OBJECTS_PATH