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:: --GCC=compiler_name (gnatmake)
144 :switch:`--GCC={compiler_name}`
145 Program used for compiling. The default is ``gcc``. You need to use
146 quotes around ``compiler_name`` if ``compiler_name`` contains
147 spaces or other separator characters.
148 As an example ``--GCC="foo -x -y"``
149 will instruct ``gnatmake`` to use ``foo -x -y`` as your
150 compiler. A limitation of this syntax is that the name and path name of
151 the executable itself must not include any embedded spaces. Note that
152 switch :switch:`-c` is always inserted after your command name. Thus in the
153 above example the compiler command that will be used by ``gnatmake``
154 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
155 used, only the last ``compiler_name`` is taken into account. However,
156 all the additional switches are also taken into account. Thus,
157 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
158 ``--GCC="bar -x -y -z -t"``.
161 .. index:: --GNATBIND=binder_name (gnatmake)
163 :switch:`--GNATBIND={binder_name}`
164 Program used for binding. The default is ``gnatbind``. You need to
165 use quotes around ``binder_name`` if ``binder_name`` contains spaces
166 or other separator characters.
167 As an example ``--GNATBIND="bar -x -y"``
168 will instruct ``gnatmake`` to use ``bar -x -y`` as your
169 binder. Binder switches that are normally appended by ``gnatmake``
170 to ``gnatbind`` are now appended to the end of ``bar -x -y``.
171 A limitation of this syntax is that the name and path name of the executable
172 itself must not include any embedded spaces.
174 .. index:: --GNATLINK=linker_name (gnatmake)
176 :switch:`--GNATLINK={linker_name}`
177 Program used for linking. The default is ``gnatlink``. You need to
178 use quotes around ``linker_name`` if ``linker_name`` contains spaces
179 or other separator characters.
180 As an example ``--GNATLINK="lan -x -y"``
181 will instruct ``gnatmake`` to use ``lan -x -y`` as your
182 linker. Linker switches that are normally appended by ``gnatmake`` to
183 ``gnatlink`` are now appended to the end of ``lan -x -y``.
184 A limitation of this syntax is that the name and path name of the executable
185 itself must not include any embedded spaces.
187 :switch:`--create-map-file`
188 When linking an executable, create a map file. The name of the map file
189 has the same name as the executable with extension ".map".
191 :switch:`--create-map-file={mapfile}`
192 When linking an executable, create a map file with the specified name.
194 .. index:: --create-missing-dirs (gnatmake)
196 :switch:`--create-missing-dirs`
197 When using project files (:switch:`-P{project}`), automatically create
198 missing object directories, library directories and exec
201 :switch:`--single-compile-per-obj-dir`
202 Disallow simultaneous compilations in the same object directory when
203 project files are used.
205 :switch:`--subdirs={subdir}`
206 Actual object directory of each project file is the subdirectory subdir of the
207 object directory specified or defaulted in the project file.
209 :switch:`--unchecked-shared-lib-imports`
210 By default, shared library projects are not allowed to import static library
211 projects. When this switch is used on the command line, this restriction is
214 :switch:`--source-info={source info file}`
215 Specify a source info file. This switch is active only when project files
216 are used. If the source info file is specified as a relative path, then it is
217 relative to the object directory of the main project. If the source info file
218 does not exist, then after the Project Manager has successfully parsed and
219 processed the project files and found the sources, it creates the source info
220 file. If the source info file already exists and can be read successfully,
221 then the Project Manager will get all the needed information about the sources
222 from the source info file and will not look for them. This reduces the time
223 to process the project files, especially when looking for sources that take a
224 long time. If the source info file exists but cannot be parsed successfully,
225 the Project Manager will attempt to recreate it. If the Project Manager fails
226 to create the source info file, a message is issued, but gnatmake does not
227 fail. ``gnatmake`` "trusts" the source info file. This means that
228 if the source files have changed (addition, deletion, moving to a different
229 source directory), then the source info file need to be deleted and recreated.
232 .. index:: -a (gnatmake)
235 Consider all files in the make process, even the GNAT internal system
236 files (for example, the predefined Ada library files), as well as any
237 locked files. Locked files are files whose ALI file is write-protected.
239 ``gnatmake`` does not check these files,
240 because the assumption is that the GNAT internal files are properly up
241 to date, and also that any write protected ALI files have been properly
242 installed. Note that if there is an installation problem, such that one
243 of these files is not up to date, it will be properly caught by the
245 You may have to specify this switch if you are working on GNAT
246 itself. The switch ``-a`` is also useful
247 in conjunction with ``-f``
248 if you need to recompile an entire application,
249 including run-time files, using special configuration pragmas,
250 such as a ``Normalize_Scalars`` pragma.
253 ``gnatmake -a`` compiles all GNAT
255 ``gcc -c -gnatpg`` rather than ``gcc -c``.
258 .. index:: -b (gnatmake)
261 Bind only. Can be combined with :switch:`-c` to do
262 compilation and binding, but no link.
263 Can be combined with :switch:`-l`
264 to do binding and linking. When not combined with
266 all the units in the closure of the main program must have been previously
267 compiled and must be up to date. The root unit specified by ``file_name``
268 may be given without extension, with the source extension or, if no GNAT
269 Project File is specified, with the ALI file extension.
272 .. index:: -c (gnatmake)
275 Compile only. Do not perform binding, except when :switch:`-b`
276 is also specified. Do not perform linking, except if both
278 :switch:`-l` are also specified.
279 If the root unit specified by ``file_name`` is not a main unit, this is the
280 default. Otherwise ``gnatmake`` will attempt binding and linking
281 unless all objects are up to date and the executable is more recent than
285 .. index:: -C (gnatmake)
288 Use a temporary mapping file. A mapping file is a way to communicate
289 to the compiler two mappings: from unit names to file names (without
290 any directory information) and from file names to path names (with
291 full directory information). A mapping file can make the compiler's
292 file searches faster, especially if there are many source directories,
293 or the sources are read over a slow network connection. If
294 :switch:`-P` is used, a mapping file is always used, so
295 :switch:`-C` is unnecessary; in this case the mapping file
296 is initially populated based on the project file. If
297 :switch:`-C` is used without
299 the mapping file is initially empty. Each invocation of the compiler
300 will add any newly accessed sources to the mapping file.
303 .. index:: -C= (gnatmake)
306 Use a specific mapping file. The file, specified as a path name (absolute or
307 relative) by this switch, should already exist, otherwise the switch is
308 ineffective. The specified mapping file will be communicated to the compiler.
309 This switch is not compatible with a project file
310 (-P`file`) or with multiple compiling processes
311 (-jnnn, when nnn is greater than 1).
314 .. index:: -d (gnatmake)
317 Display progress for each source, up to date or not, as a single line:
321 completed x out of y (zz%)
323 If the file needs to be compiled this is displayed after the invocation of
324 the compiler. These lines are displayed even in quiet output mode.
327 .. index:: -D (gnatmake)
330 Put all object files and ALI file in directory ``dir``.
331 If the :switch:`-D` switch is not used, all object files
332 and ALI files go in the current working directory.
334 This switch cannot be used when using a project file.
337 .. index:: -eI (gnatmake)
340 Indicates that the main source is a multi-unit source and the rank of the unit
341 in the source file is nnn. nnn needs to be a positive number and a valid
342 index in the source. This switch cannot be used when ``gnatmake`` is
343 invoked for several mains.
346 .. index:: -eL (gnatmake)
347 .. index:: symbolic links
350 Follow all symbolic links when processing project files.
351 This should be used if your project uses symbolic links for files or
352 directories, but is not needed in other cases.
354 .. index:: naming scheme
356 This also assumes that no directory matches the naming scheme for files (for
357 instance that you do not have a directory called "sources.ads" when using the
358 default GNAT naming scheme).
360 When you do not have to use this switch (i.e., by default), gnatmake is able to
361 save a lot of system calls (several per source file and object file), which
362 can result in a significant speed up to load and manipulate a project file,
363 especially when using source files from a remote system.
366 .. index:: -eS (gnatmake)
369 Output the commands for the compiler, the binder and the linker
371 instead of standard error.
374 .. index:: -f (gnatmake)
377 Force recompilations. Recompile all sources, even though some object
378 files may be up to date, but don't recompile predefined or GNAT internal
379 files or locked files (files with a write-protected ALI file),
380 unless the :switch:`-a` switch is also specified.
383 .. index:: -F (gnatmake)
386 When using project files, if some errors or warnings are detected during
387 parsing and verbose mode is not in effect (no use of switch
388 -v), then error lines start with the full path name of the project
389 file, rather than its simple file name.
392 .. index:: -g (gnatmake)
395 Enable debugging. This switch is simply passed to the compiler and to the
399 .. index:: -i (gnatmake)
402 In normal mode, ``gnatmake`` compiles all object files and ALI files
403 into the current directory. If the :switch:`-i` switch is used,
404 then instead object files and ALI files that already exist are overwritten
405 in place. This means that once a large project is organized into separate
406 directories in the desired manner, then ``gnatmake`` will automatically
407 maintain and update this organization. If no ALI files are found on the
408 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
409 the new object and ALI files are created in the
410 directory containing the source being compiled. If another organization
411 is desired, where objects and sources are kept in different directories,
412 a useful technique is to create dummy ALI files in the desired directories.
413 When detecting such a dummy file, ``gnatmake`` will be forced to
414 recompile the corresponding source file, and it will be put the resulting
415 object and ALI files in the directory where it found the dummy file.
418 .. index:: -j (gnatmake)
419 .. index:: Parallel make
422 Use ``n`` processes to carry out the (re)compilations. On a multiprocessor
423 machine compilations will occur in parallel. If ``n`` is 0, then the
424 maximum number of parallel compilations is the number of core processors
425 on the platform. In the event of compilation errors, messages from various
426 compilations might get interspersed (but ``gnatmake`` will give you the
427 full ordered list of failing compiles at the end). If this is problematic,
428 rerun the make process with n set to 1 to get a clean list of messages.
431 .. index:: -k (gnatmake)
434 Keep going. Continue as much as possible after a compilation error. To
435 ease the programmer's task in case of compilation errors, the list of
436 sources for which the compile fails is given when ``gnatmake``
439 If ``gnatmake`` is invoked with several :file:`file_names` and with this
440 switch, if there are compilation errors when building an executable,
441 ``gnatmake`` will not attempt to build the following executables.
444 .. index:: -l (gnatmake)
447 Link only. Can be combined with :switch:`-b` to binding
448 and linking. Linking will not be performed if combined with
450 but not with :switch:`-b`.
451 When not combined with :switch:`-b`
452 all the units in the closure of the main program must have been previously
453 compiled and must be up to date, and the main program needs to have been bound.
454 The root unit specified by ``file_name``
455 may be given without extension, with the source extension or, if no GNAT
456 Project File is specified, with the ALI file extension.
459 .. index:: -m (gnatmake)
462 Specify that the minimum necessary amount of recompilations
463 be performed. In this mode ``gnatmake`` ignores time
464 stamp differences when the only
465 modifications to a source file consist in adding/removing comments,
466 empty lines, spaces or tabs. This means that if you have changed the
467 comments in a source file or have simply reformatted it, using this
468 switch will tell ``gnatmake`` not to recompile files that depend on it
469 (provided other sources on which these files depend have undergone no
470 semantic modifications). Note that the debugging information may be
471 out of date with respect to the sources if the :switch:`-m` switch causes
472 a compilation to be switched, so the use of this switch represents a
473 trade-off between compilation time and accurate debugging information.
476 .. index:: Dependencies, producing list
477 .. index:: -M (gnatmake)
480 Check if all objects are up to date. If they are, output the object
481 dependences to :file:`stdout` in a form that can be directly exploited in
482 a :file:`Makefile`. By default, each source file is prefixed with its
483 (relative or absolute) directory name. This name is whatever you
484 specified in the various :switch:`-aI`
485 and :switch:`-I` switches. If you use
486 ``gnatmake -M`` :switch:`-q`
487 (see below), only the source file names,
488 without relative paths, are output. If you just specify the :switch:`-M`
489 switch, dependencies of the GNAT internal system files are omitted. This
490 is typically what you want. If you also specify
491 the :switch:`-a` switch,
492 dependencies of the GNAT internal files are also listed. Note that
493 dependencies of the objects in external Ada libraries (see
494 switch :switch:`-aL{dir}` in the following list)
498 .. index:: -n (gnatmake)
501 Don't compile, bind, or link. Checks if all objects are up to date.
502 If they are not, the full name of the first file that needs to be
503 recompiled is printed.
504 Repeated use of this option, followed by compiling the indicated source
505 file, will eventually result in recompiling all required units.
508 .. index:: -o (gnatmake)
510 :switch:`-o {exec_name}`
511 Output executable name. The name of the final executable program will be
512 ``exec_name``. If the :switch:`-o` switch is omitted the default
513 name for the executable will be the name of the input file in appropriate form
514 for an executable file on the host system.
516 This switch cannot be used when invoking ``gnatmake`` with several
520 .. index:: -p (gnatmake)
523 Same as :switch:`--create-missing-dirs`
525 .. index:: -P (gnatmake)
527 :switch:`-P{project}`
528 Use project file ``project``. Only one such switch can be used.
531 :ref:`gnatmake_and_Project_Files`.
534 .. index:: -q (gnatmake)
537 Quiet. When this flag is not set, the commands carried out by
538 ``gnatmake`` are displayed.
541 .. index:: -s (gnatmake)
544 Recompile if compiler switches have changed since last compilation.
545 All compiler switches but -I and -o are taken into account in the
547 orders between different 'first letter' switches are ignored, but
548 orders between same switches are taken into account. For example,
549 :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O`
550 is equivalent to :switch:`-O -g`.
552 This switch is recommended when Integrated Preprocessing is used.
555 .. index:: -u (gnatmake)
558 Unique. Recompile at most the main files. It implies -c. Combined with
559 -f, it is equivalent to calling the compiler directly. Note that using
560 -u with a project file and no main has a special meaning.
563 (See :ref:`Project_Files_and_Main_Subprograms`.)
566 .. index:: -U (gnatmake)
569 When used without a project file or with one or several mains on the command
570 line, is equivalent to -u. When used with a project file and no main
571 on the command line, all sources of all project files are checked and compiled
572 if not up to date, and libraries are rebuilt, if necessary.
575 .. index:: -v (gnatmake)
578 Verbose. Display the reason for all recompilations ``gnatmake``
579 decides are necessary, with the highest verbosity level.
582 .. index:: -vl (gnatmake)
585 Verbosity level Low. Display fewer lines than in verbosity Medium.
588 .. index:: -vm (gnatmake)
591 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
594 .. index:: -vm (gnatmake)
597 Verbosity level High. Equivalent to -v.
601 Indicate the verbosity of the parsing of GNAT project files.
602 See :ref:`Switches_Related_to_Project_Files`.
605 .. index:: -x (gnatmake)
608 Indicate that sources that are not part of any Project File may be compiled.
609 Normally, when using Project Files, only sources that are part of a Project
610 File may be compile. When this switch is used, a source outside of all Project
611 Files may be compiled. The ALI file and the object file will be put in the
612 object directory of the main Project. The compilation switches used will only
613 be those specified on the command line. Even when
614 :switch:`-x` is used, mains specified on the
615 command line need to be sources of a project file.
618 :switch:`-X{name}={value}`
619 Indicate that external variable ``name`` has the value ``value``.
620 The Project Manager will use this value for occurrences of
621 ``external(name)`` when parsing the project file.
622 :ref:`Switches_Related_to_Project_Files`.
625 .. index:: -z (gnatmake)
628 No main subprogram. Bind and link the program even if the unit name
629 given on the command line is a package name. The resulting executable
630 will execute the elaboration routines of the package and its closure,
631 then the finalization routines.
634 .. rubric:: GCC switches
636 Any uppercase or multi-character switch that is not a ``gnatmake`` switch
637 is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
640 .. rubric:: Source and library search path switches
642 .. index:: -aI (gnatmake)
645 When looking for source files also look in directory ``dir``.
646 The order in which source files search is undertaken is
647 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
650 .. index:: -aL (gnatmake)
653 Consider ``dir`` as being an externally provided Ada library.
654 Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI`
655 files have been located in directory ``dir``. This allows you to have
656 missing bodies for the units in ``dir`` and to ignore out of date bodies
657 for the same units. You still need to specify
658 the location of the specs for these units by using the switches
659 :switch:`-aI{dir}` or :switch:`-I{dir}`.
660 Note: this switch is provided for compatibility with previous versions
661 of ``gnatmake``. The easier method of causing standard libraries
662 to be excluded from consideration is to write-protect the corresponding
666 .. index:: -aO (gnatmake)
669 When searching for library and object files, look in directory
670 ``dir``. The order in which library files are searched is described in
671 :ref:`Search_Paths_for_gnatbind`.
674 .. index:: Search paths, for gnatmake
675 .. index:: -A (gnatmake)
678 Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`.
681 .. index:: -I (gnatmake)
684 Equivalent to :switch:`-aO{dir} -aI{dir}`.
687 .. index:: -I- (gnatmake)
688 .. index:: Source files, suppressing search
691 Do not look for source files in the directory containing the source
692 file named in the command line.
693 Do not look for ALI or object files in the directory
694 where ``gnatmake`` was invoked.
697 .. index:: -L (gnatmake)
698 .. index:: Linker libraries
701 Add directory ``dir`` to the list of directories in which the linker
702 will search for libraries. This is equivalent to
703 :switch:`-largs` :switch:`-L{dir}`.
704 Furthermore, under Windows, the sources pointed to by the libraries path
705 set in the registry are not searched for.
708 .. index:: -nostdinc (gnatmake)
711 Do not look for source files in the system default directory.
714 .. index:: -nostdlib (gnatmake)
717 Do not look for library files in the system default directory.
720 .. index:: --RTS (gnatmake)
722 :switch:`--RTS={rts-path}`
723 Specifies the default location of the run-time library. GNAT looks for the
725 in the following directories, and stops as soon as a valid run-time is found
726 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
727 :file:`ada_object_path` present):
729 * *<current directory>/$rts_path*
731 * *<default-search-dir>/$rts_path*
733 * *<default-search-dir>/rts-$rts_path*
735 * The selected path is handled like a normal RTS path.
738 .. _Mode_Switches_for_gnatmake:
740 Mode Switches for ``gnatmake``
741 ------------------------------
743 The mode switches (referred to as ``mode_switches``) allow the
744 inclusion of switches that are to be passed to the compiler itself, the
745 binder or the linker. The effect of a mode switch is to cause all
746 subsequent switches up to the end of the switch list, or up to the next
747 mode switch, to be interpreted as switches to be passed on to the
748 designated component of GNAT.
750 .. index:: -cargs (gnatmake)
752 :switch:`-cargs {switches}`
753 Compiler switches. Here ``switches`` is a list of switches
754 that are valid switches for ``gcc``. They will be passed on to
755 all compile steps performed by ``gnatmake``.
758 .. index:: -bargs (gnatmake)
760 :switch:`-bargs {switches}`
761 Binder switches. Here ``switches`` is a list of switches
762 that are valid switches for ``gnatbind``. They will be passed on to
763 all bind steps performed by ``gnatmake``.
766 .. index:: -largs (gnatmake)
768 :switch:`-largs {switches}`
769 Linker switches. Here ``switches`` is a list of switches
770 that are valid switches for ``gnatlink``. They will be passed on to
771 all link steps performed by ``gnatmake``.
774 .. index:: -margs (gnatmake)
776 :switch:`-margs {switches}`
777 Make switches. The switches are directly interpreted by ``gnatmake``,
778 regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs`
782 .. _Notes_on_the_Command_Line:
784 Notes on the Command Line
785 -------------------------
787 This section contains some additional useful notes on the operation
788 of the ``gnatmake`` command.
790 .. index:: Recompilation (by gnatmake)
792 * If ``gnatmake`` finds no ALI files, it recompiles the main program
793 and all other units required by the main program.
794 This means that ``gnatmake``
795 can be used for the initial compile, as well as during subsequent steps of
796 the development cycle.
798 * If you enter ``gnatmake foo.adb``, where ``foo``
799 is a subunit or body of a generic unit, ``gnatmake`` recompiles
800 :file:`foo.adb` (because it finds no ALI) and stops, issuing a
803 * In ``gnatmake`` the switch :switch:`-I`
804 is used to specify both source and
805 library file paths. Use :switch:`-aI`
806 instead if you just want to specify
807 source paths only and :switch:`-aO`
808 if you want to specify library paths
811 * ``gnatmake`` will ignore any files whose ALI file is write-protected.
812 This may conveniently be used to exclude standard libraries from
813 consideration and in particular it means that the use of the
814 :switch:`-f` switch will not recompile these files
815 unless :switch:`-a` is also specified.
817 * ``gnatmake`` has been designed to make the use of Ada libraries
818 particularly convenient. Assume you have an Ada library organized
819 as follows: *obj-dir* contains the objects and ALI files for
820 of your Ada compilation units,
821 whereas *include-dir* contains the
822 specs of these units, but no bodies. Then to compile a unit
823 stored in ``main.adb``, which uses this Ada library you would just type:
827 $ gnatmake -aI`include-dir` -aL`obj-dir` main
829 * Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)`
830 switch provides a mechanism for avoiding unnecessary recompilations. Using
832 you can update the comments/format of your
833 source files without having to recompile everything. Note, however, that
834 adding or deleting lines in a source files may render its debugging
835 info obsolete. If the file in question is a spec, the impact is rather
836 limited, as that debugging info will only be useful during the
837 elaboration phase of your program. For bodies the impact can be more
838 significant. In all events, your debugger will warn you if a source file
839 is more recent than the corresponding object, and alert you to the fact
840 that the debugging information may be out of date.
843 .. _How_gnatmake_Works:
845 How ``gnatmake`` Works
846 ----------------------
848 Generally ``gnatmake`` automatically performs all necessary
849 recompilations and you don't need to worry about how it works. However,
850 it may be useful to have some basic understanding of the ``gnatmake``
851 approach and in particular to understand how it uses the results of
852 previous compilations without incorrectly depending on them.
854 First a definition: an object file is considered *up to date* if the
855 corresponding ALI file exists and if all the source files listed in the
856 dependency section of this ALI file have time stamps matching those in
857 the ALI file. This means that neither the source file itself nor any
858 files that it depends on have been modified, and hence there is no need
859 to recompile this file.
861 ``gnatmake`` works by first checking if the specified main unit is up
862 to date. If so, no compilations are required for the main unit. If not,
863 ``gnatmake`` compiles the main program to build a new ALI file that
864 reflects the latest sources. Then the ALI file of the main unit is
865 examined to find all the source files on which the main program depends,
866 and ``gnatmake`` recursively applies the above procedure on all these
869 This process ensures that ``gnatmake`` only trusts the dependencies
870 in an existing ALI file if they are known to be correct. Otherwise it
871 always recompiles to determine a new, guaranteed accurate set of
872 dependencies. As a result the program is compiled 'upside down' from what may
873 be more familiar as the required order of compilation in some other Ada
874 systems. In particular, clients are compiled before the units on which
875 they depend. The ability of GNAT to compile in any order is critical in
876 allowing an order of compilation to be chosen that guarantees that
877 ``gnatmake`` will recompute a correct set of new dependencies if
880 When invoking ``gnatmake`` with several ``file_names``, if a unit is
881 imported by several of the executables, it will be recompiled at most once.
883 Note: when using non-standard naming conventions
884 (:ref:`Using_Other_File_Names`), changing through a configuration pragmas
885 file the version of a source and invoking ``gnatmake`` to recompile may
886 have no effect, if the previous version of the source is still accessible
887 by ``gnatmake``. It may be necessary to use the switch
891 .. _Examples_of_gnatmake_Usage:
893 Examples of ``gnatmake`` Usage
894 ------------------------------
897 Compile all files necessary to bind and link the main program
898 :file:`hello.adb` (containing unit ``Hello``) and bind and link the
899 resulting object files to generate an executable file :file:`hello`.
901 *gnatmake main1 main2 main3*
902 Compile all files necessary to bind and link the main programs
903 :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb`
904 (containing unit ``Main2``) and :file:`main3.adb`
905 (containing unit ``Main3``) and bind and link the resulting object files
906 to generate three executable files :file:`main1`,
907 :file:`main2` and :file:`main3`.
909 *gnatmake -q Main_Unit -cargs -O2 -bargs -l*
910 Compile all files necessary to bind and link the main program unit
911 ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will
912 be done with optimization level 2 and the order of elaboration will be
913 listed by the binder. ``gnatmake`` will operate in quiet mode, not
914 displaying commands it is executing.
917 .. _Compiling_with_gcc:
919 Compiling with ``gcc``
920 ======================
922 This section discusses how to compile Ada programs using the ``gcc``
923 command. It also describes the set of switches
924 that can be used to control the behavior of the compiler.
926 .. _Compiling_Programs:
931 The first step in creating an executable program is to compile the units
932 of the program using the ``gcc`` command. You must compile the
935 * the body file (:file:`.adb`) for a library level subprogram or generic
938 * the spec file (:file:`.ads`) for a library level package or generic
939 package that has no body
941 * the body file (:file:`.adb`) for a library level package
942 or generic package that has a body
944 You need *not* compile the following files
946 * the spec of a library unit which has a body
950 because they are compiled as part of compiling related units. GNAT
952 when the corresponding body is compiled, and subunits when the parent is
955 .. index:: cannot generate code
957 If you attempt to compile any of these files, you will get one of the
958 following error messages (where ``fff`` is the name of the file you
963 cannot generate code for file ``fff`` (package spec)
964 to check package spec, use -gnatc
966 cannot generate code for file ``fff`` (missing subunits)
967 to check parent unit, use -gnatc
969 cannot generate code for file ``fff`` (subprogram spec)
970 to check subprogram spec, use -gnatc
972 cannot generate code for file ``fff`` (subunit)
973 to check subunit, use -gnatc
976 As indicated by the above error messages, if you want to submit
977 one of these files to the compiler to check for correct semantics
978 without generating code, then use the :switch:`-gnatc` switch.
980 The basic command for compiling a file containing an Ada unit is:
984 $ gcc -c [switches] <file name>
986 where ``file name`` is the name of the Ada file (usually
987 having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
989 :switch:`-c` switch to tell ``gcc`` to compile, but not link, the file.
990 The result of a successful compilation is an object file, which has the
991 same name as the source file but an extension of :file:`.o` and an Ada
992 Library Information (ALI) file, which also has the same name as the
993 source file, but with :file:`.ali` as the extension. GNAT creates these
994 two output files in the current directory, but you may specify a source
995 file in any directory using an absolute or relative path specification
996 containing the directory information.
998 TESTING: the :switch:`--foobar{NN}` switch
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 :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.
1237 .. index:: -fdump-scos (gcc)
1239 :switch:`-fdump-scos`
1240 Generates SCO (Source Coverage Obligation) information in the ALI file.
1241 This information is used by advanced coverage tools. See unit :file:`SCOs`
1242 in the compiler sources for details in files :file:`scos.ads` and
1246 .. index:: -fgnat-encodings (gcc)
1248 :switch:`-fgnat-encodings=[all|gdb|minimal]`
1249 This switch controls the balance between GNAT encodings and standard DWARF
1250 emitted in the debug information.
1253 .. index:: -flto (gcc)
1255 :switch:`-flto[={n}]`
1256 Enables Link Time Optimization. This switch must be used in conjunction
1257 with the :switch:`-Ox` switches (but not with the :switch:`-gnatn` switch
1258 since it is a full replacement for the latter) and instructs the compiler
1259 to defer most optimizations until the link stage. The advantage of this
1260 approach is that the compiler can do a whole-program analysis and choose
1261 the best interprocedural optimization strategy based on a complete view
1262 of the program, instead of a fragmentary view with the usual approach.
1263 This can also speed up the compilation of big programs and reduce the
1264 size of the executable, compared with a traditional per-unit compilation
1265 with inlining across units enabled by the :switch:`-gnatn` switch.
1266 The drawback of this approach is that it may require more memory and that
1267 the debugging information generated by -g with it might be hardly usable.
1268 The switch, as well as the accompanying :switch:`-Ox` switches, must be
1269 specified both for the compilation and the link phases.
1270 If the ``n`` parameter is specified, the optimization and final code
1271 generation at link time are executed using ``n`` parallel jobs by
1272 means of an installed ``make`` program.
1275 .. index:: -fno-inline (gcc)
1277 :switch:`-fno-inline`
1278 Suppresses all inlining, unless requested with pragma ``Inline_Always``. The
1279 effect is enforced regardless of other optimization or inlining switches.
1280 Note that inlining can also be suppressed on a finer-grained basis with
1281 pragma ``No_Inline``.
1284 .. index:: -fno-inline-functions (gcc)
1286 :switch:`-fno-inline-functions`
1287 Suppresses automatic inlining of subprograms, which is enabled
1288 if :switch:`-O3` is used.
1291 .. index:: -fno-inline-small-functions (gcc)
1293 :switch:`-fno-inline-small-functions`
1294 Suppresses automatic inlining of small subprograms, which is enabled
1295 if :switch:`-O2` is used.
1298 .. index:: -fno-inline-functions-called-once (gcc)
1300 :switch:`-fno-inline-functions-called-once`
1301 Suppresses inlining of subprograms local to the unit and called once
1302 from within it, which is enabled if :switch:`-O1` is used.
1305 .. index:: -fno-ivopts (gcc)
1307 :switch:`-fno-ivopts`
1308 Suppresses high-level loop induction variable optimizations, which are
1309 enabled if :switch:`-O1` is used. These optimizations are generally
1310 profitable but, for some specific cases of loops with numerous uses
1311 of the iteration variable that follow a common pattern, they may end
1312 up destroying the regularity that could be exploited at a lower level
1313 and thus producing inferior code.
1316 .. index:: -fno-strict-aliasing (gcc)
1318 :switch:`-fno-strict-aliasing`
1319 Causes the compiler to avoid assumptions regarding non-aliasing
1320 of objects of different types. See
1321 :ref:`Optimization_and_Strict_Aliasing` for details.
1324 .. index:: -fno-strict-overflow (gcc)
1326 :switch:`-fno-strict-overflow`
1327 Causes the compiler to avoid assumptions regarding the rules of signed
1328 integer overflow. These rules specify that signed integer overflow will
1329 result in a Constraint_Error exception at run time and are enforced in
1330 default mode by the compiler, so this switch should not be necessary in
1331 normal operating mode. It might be useful in conjunction with :switch:`-gnato0`
1332 for very peculiar cases of low-level programming.
1335 .. index:: -fstack-check (gcc)
1337 :switch:`-fstack-check`
1338 Activates stack checking.
1339 See :ref:`Stack_Overflow_Checking` for details.
1342 .. index:: -fstack-usage (gcc)
1344 :switch:`-fstack-usage`
1345 Makes the compiler output stack usage information for the program, on a
1346 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
1352 Generate debugging information. This information is stored in the object
1353 file and copied from there to the final executable file by the linker,
1354 where it can be read by the debugger. You must use the
1355 :switch:`-g` switch if you plan on using the debugger.
1358 .. index:: -gnat05 (gcc)
1361 Allow full Ada 2005 features.
1364 .. index:: -gnat12 (gcc)
1367 Allow full Ada 2012 features.
1369 .. index:: -gnat83 (gcc)
1371 .. index:: -gnat2005 (gcc)
1374 Allow full Ada 2005 features (same as :switch:`-gnat05`)
1377 .. index:: -gnat2012 (gcc)
1380 Allow full Ada 2012 features (same as :switch:`-gnat12`)
1384 Enforce Ada 83 restrictions.
1387 .. index:: -gnat95 (gcc)
1390 Enforce Ada 95 restrictions.
1392 Note: for compatibility with some Ada 95 compilers which support only
1393 the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can
1394 be used along with :switch:`-gnat95` to achieve a similar effect with GNAT.
1396 :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword
1397 and handle its associated semantic checks, even in Ada 95 mode.
1400 .. index:: -gnata (gcc)
1403 Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be
1404 activated. Note that these pragmas can also be controlled using the
1405 configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``.
1406 It also activates pragmas ``Check``, ``Precondition``, and
1407 ``Postcondition``. Note that these pragmas can also be controlled
1408 using the configuration pragma ``Check_Policy``. In Ada 2012, it
1409 also activates all assertions defined in the RM as aspects: preconditions,
1410 postconditions, type invariants and (sub)type predicates. In all Ada modes,
1411 corresponding pragmas for type invariants and (sub)type predicates are
1412 also activated. The default is that all these assertions are disabled,
1413 and have no effect, other than being checked for syntactic validity, and
1414 in the case of subtype predicates, constructions such as membership tests
1415 still test predicates even if assertions are turned off.
1418 .. index:: -gnatA (gcc)
1421 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
1425 .. index:: -gnatb (gcc)
1428 Generate brief messages to :file:`stderr` even if verbose mode set.
1431 .. index:: -gnatB (gcc)
1434 Assume no invalid (bad) values except for 'Valid attribute use
1435 (:ref:`Validity_Checking`).
1438 .. index:: -gnatc (gcc)
1441 Check syntax and semantics only (no code generation attempted). When the
1442 compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is
1443 only given to the compiler (after :switch:`-cargs` or in package Compiler of
1444 the project file, ``gnatmake`` will fail because it will not find the
1445 object file after compilation. If ``gnatmake`` is called with
1446 :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package
1447 Builder of the project file) then ``gnatmake`` will not fail because
1448 it will not look for the object files after compilation, and it will not try
1452 .. index:: -gnatC (gcc)
1455 Generate CodePeer intermediate format (no code generation attempted).
1456 This switch will generate an intermediate representation suitable for
1457 use by CodePeer (:file:`.scil` files). This switch is not compatible with
1458 code generation (it will, among other things, disable some switches such
1459 as -gnatn, and enable others such as -gnata).
1462 .. index:: -gnatd (gcc)
1465 Specify debug options for the compiler. The string of characters after
1466 the :switch:`-gnatd` specify the specific debug options. The possible
1467 characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
1468 compiler source file :file:`debug.adb` for details of the implemented
1469 debug options. Certain debug options are relevant to applications
1470 programmers, and these are documented at appropriate points in this
1474 .. index:: -gnatD[nn] (gcc)
1477 Create expanded source files for source level debugging. This switch
1478 also suppresses generation of cross-reference information
1479 (see :switch:`-gnatx`). Note that this switch is not allowed if a previous
1480 -gnatR switch has been given, since these two switches are not compatible.
1483 .. index:: -gnateA (gcc)
1486 Check that the actual parameters of a subprogram call are not aliases of one
1487 another. To qualify as aliasing, the actuals must denote objects of a composite
1488 type, their memory locations must be identical or overlapping, and at least one
1489 of the corresponding formal parameters must be of mode OUT or IN OUT.
1494 type Rec_Typ is record
1495 Data : Integer := 0;
1498 function Self (Val : Rec_Typ) return Rec_Typ is
1503 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
1506 end Detect_Aliasing;
1510 Detect_Aliasing (Obj, Obj);
1511 Detect_Aliasing (Obj, Self (Obj));
1514 In the example above, the first call to ``Detect_Aliasing`` fails with a
1515 ``Program_Error`` at run time because the actuals for ``Val_1`` and
1516 ``Val_2`` denote the same object. The second call executes without raising
1517 an exception because ``Self(Obj)`` produces an anonymous object which does
1518 not share the memory location of ``Obj``.
1521 .. index:: -gnatec (gcc)
1523 :switch:`-gnatec={path}`
1524 Specify a configuration pragma file
1525 (the equal sign is optional)
1526 (:ref:`The_Configuration_Pragmas_Files`).
1529 .. index:: -gnateC (gcc)
1532 Generate CodePeer messages in a compiler-like format. This switch is only
1533 effective if :switch:`-gnatcC` is also specified and requires an installation
1537 .. index:: -gnated (gcc)
1540 Disable atomic synchronization
1543 .. index:: -gnateD (gcc)
1545 :switch:`-gnateDsymbol[={value}]`
1546 Defines a symbol, associated with ``value``, for preprocessing.
1547 (:ref:`Integrated_Preprocessing`).
1550 .. index:: -gnateE (gcc)
1553 Generate extra information in exception messages. In particular, display
1554 extra column information and the value and range associated with index and
1555 range check failures, and extra column information for access checks.
1556 In cases where the compiler is able to determine at compile time that
1557 a check will fail, it gives a warning, and the extra information is not
1558 produced at run time.
1561 .. index:: -gnatef (gcc)
1564 Display full source path name in brief error messages.
1567 .. index:: -gnateF (gcc)
1570 Check for overflow on all floating-point operations, including those
1571 for unconstrained predefined types. See description of pragma
1572 ``Check_Float_Overflow`` in GNAT RM.
1575 .. index:: -gnateg (gcc)
1580 The :switch:`-gnatc` switch must always be specified before this switch, e.g.
1581 :switch:`-gnatceg`. Generate a C header from the Ada input file. See
1582 :ref:`Generating_C_Headers_for_Ada_Specifications` for more
1586 .. index:: -gnateG (gcc)
1589 Save result of preprocessing in a text file.
1592 .. index:: -gnatei (gcc)
1594 :switch:`-gnatei{nnn}`
1595 Set maximum number of instantiations during compilation of a single unit to
1596 ``nnn``. This may be useful in increasing the default maximum of 8000 for
1597 the rare case when a single unit legitimately exceeds this limit.
1600 .. index:: -gnateI (gcc)
1602 :switch:`-gnateI{nnn}`
1603 Indicates that the source is a multi-unit source and that the index of the
1604 unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need
1605 to be a valid index in the multi-unit source.
1608 .. index:: -gnatel (gcc)
1611 This switch can be used with the static elaboration model to issue info
1613 where implicit ``pragma Elaborate`` and ``pragma Elaborate_All``
1614 are generated. This is useful in diagnosing elaboration circularities
1615 caused by these implicit pragmas when using the static elaboration
1616 model. See See the section in this guide on elaboration checking for
1617 further details. These messages are not generated by default, and are
1618 intended only for temporary use when debugging circularity problems.
1621 .. index:: -gnatel (gcc)
1624 This switch turns off the info messages about implicit elaboration pragmas.
1627 .. index:: -gnatem (gcc)
1629 :switch:`-gnatem={path}`
1630 Specify a mapping file
1631 (the equal sign is optional)
1632 (:ref:`Units_to_Sources_Mapping_Files`).
1635 .. index:: -gnatep (gcc)
1637 :switch:`-gnatep={file}`
1638 Specify a preprocessing data file
1639 (the equal sign is optional)
1640 (:ref:`Integrated_Preprocessing`).
1643 .. index:: -gnateP (gcc)
1646 Turn categorization dependency errors into warnings.
1647 Ada requires that units that WITH one another have compatible categories, for
1648 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
1649 these errors become warnings (which can be ignored, or suppressed in the usual
1650 manner). This can be useful in some specialized circumstances such as the
1651 temporary use of special test software.
1654 .. index:: -gnateS (gcc)
1657 Synonym of :switch:`-fdump-scos`, kept for backwards compatibility.
1660 .. index:: -gnatet=file (gcc)
1662 :switch:`-gnatet={path}`
1663 Generate target dependent information. The format of the output file is
1664 described in the section about switch :switch:`-gnateT`.
1667 .. index:: -gnateT (gcc)
1669 :switch:`-gnateT={path}`
1670 Read target dependent information, such as endianness or sizes and alignments
1671 of base type. If this switch is passed, the default target dependent
1672 information of the compiler is replaced by the one read from the input file.
1673 This is used by tools other than the compiler, e.g. to do
1674 semantic analysis of programs that will run on some other target than
1675 the machine on which the tool is run.
1677 The following target dependent values should be defined,
1678 where ``Nat`` denotes a natural integer value, ``Pos`` denotes a
1679 positive integer value, and fields marked with a question mark are
1680 boolean fields, where a value of 0 is False, and a value of 1 is True:
1685 Bits_BE : Nat; -- Bits stored big-endian?
1686 Bits_Per_Unit : Pos; -- Bits in a storage unit
1687 Bits_Per_Word : Pos; -- Bits in a word
1688 Bytes_BE : Nat; -- Bytes stored big-endian?
1689 Char_Size : Pos; -- Standard.Character'Size
1690 Double_Float_Alignment : Nat; -- Alignment of double float
1691 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
1692 Double_Size : Pos; -- Standard.Long_Float'Size
1693 Float_Size : Pos; -- Standard.Float'Size
1694 Float_Words_BE : Nat; -- Float words stored big-endian?
1695 Int_Size : Pos; -- Standard.Integer'Size
1696 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
1697 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
1698 Long_Size : Pos; -- Standard.Long_Integer'Size
1699 Maximum_Alignment : Pos; -- Maximum permitted alignment
1700 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
1701 Pointer_Size : Pos; -- System.Address'Size
1702 Short_Enums : Nat; -- Foreign enums use short size?
1703 Short_Size : Pos; -- Standard.Short_Integer'Size
1704 Strict_Alignment : Nat; -- Strict alignment?
1705 System_Allocator_Alignment : Nat; -- Alignment for malloc calls
1706 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
1707 Words_BE : Nat; -- Words stored big-endian?
1709 ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of
1710 GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be
1711 the number of bits in an addressable storage unit (byte); normally 8.`
1713 ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of
1714 GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word;
1717 ``Double_Float_Alignment``, if not zero, is the maximum alignment that the
1718 compiler can choose by default for a 64-bit floating-point type or object.
1720 ``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
1721 compiler can choose by default for a 64-bit or larger scalar type or object.
1723 ``Maximum_Alignment`` is the maximum alignment that the compiler can choose
1724 by default for a type or object, which is also the maximum alignment that can
1725 be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT
1726 / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
1727 follows: `Biggest alignment that any data type can require on this machine,
1730 ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
1731 64 for the majority of GCC targets (but can be different on some targets like
1734 ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
1735 documented as follows: `Define this macro to be the value 1 if instructions
1736 will fail to work if given data not on the nominal alignment. If instructions
1737 will merely go slower in that case, define this macro as 0.`
1739 ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
1740 by calls to ``malloc``.
1743 The format of the input file is as follows. First come the values of
1744 the variables defined above, with one line per value:
1751 where ``name`` is the name of the parameter, spelled out in full,
1752 and cased as in the above list, and ``value`` is an unsigned decimal
1753 integer. Two or more blanks separates the name from the value.
1755 All the variables must be present, in alphabetical order (i.e. the
1756 same order as the list above).
1758 Then there is a blank line to separate the two parts of the file. Then
1759 come the lines showing the floating-point types to be registered, with
1760 one line per registered mode:
1765 name digs float_rep size alignment
1768 where ``name`` is the string name of the type (which can have
1769 single spaces embedded in the name (e.g. long double), ``digs`` is
1770 the number of digits for the floating-point type, ``float_rep`` is
1771 the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
1772 AAMP), ``size`` is the size in bits, ``alignment`` is the
1773 alignment in bits. The name is followed by at least two blanks, fields
1774 are separated by at least one blank, and a LF character immediately
1775 follows the alignment field.
1777 Here is an example of a target parameterization file:
1787 Double_Float_Alignment 0
1788 Double_Scalar_Alignment 0
1793 Long_Double_Size 128
1796 Maximum_Alignment 16
1797 Max_Unaligned_Field 64
1801 System_Allocator_Alignment 16
1807 long double 18 I 80 128
1812 .. index:: -gnateu (gcc)
1815 Ignore unrecognized validity, warning, and style switches that
1816 appear after this switch is given. This may be useful when
1817 compiling sources developed on a later version of the compiler
1818 with an earlier version. Of course the earlier version must
1819 support this switch.
1822 .. index:: -gnateV (gcc)
1825 Check that all actual parameters of a subprogram call are valid according to
1826 the rules of validity checking (:ref:`Validity_Checking`).
1829 .. index:: -gnateY (gcc)
1832 Ignore all STYLE_CHECKS pragmas. Full legality checks
1833 are still carried out, but the pragmas have no effect
1834 on what style checks are active. This allows all style
1835 checking options to be controlled from the command line.
1838 .. index:: -gnatE (gcc)
1841 Dynamic elaboration checking mode enabled. For further details see
1842 :ref:`Elaboration_Order_Handling_in_GNAT`.
1845 .. index:: -gnatf (gcc)
1848 Full errors. Multiple errors per line, all undefined references, do not
1849 attempt to suppress cascaded errors.
1852 .. index:: -gnatF (gcc)
1855 Externals names are folded to all uppercase.
1858 .. index:: -gnatg (gcc)
1861 Internal GNAT implementation mode. This should not be used for applications
1862 programs, it is intended only for use by the compiler and its run-time
1863 library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
1864 implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
1865 warnings and all standard style options are turned on. All warnings and style
1866 messages are treated as errors.
1869 .. index:: -gnatG[nn] (gcc)
1872 List generated expanded code in source form.
1875 .. index:: -gnath (gcc)
1878 Output usage information. The output is written to :file:`stdout`.
1881 .. index:: -gnatH (gcc)
1884 Legacy elaboration-checking mode enabled. When this switch is in effect,
1885 the pre-18.x access-before-elaboration model becomes the de facto model.
1886 For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1889 .. index:: -gnati (gcc)
1892 Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w).
1893 For details of the possible selections for ``c``,
1894 see :ref:`Character_Set_Control`.
1897 .. index:: -gnatI (gcc)
1900 Ignore representation clauses. When this switch is used,
1901 representation clauses are treated as comments. This is useful
1902 when initially porting code where you want to ignore rep clause
1903 problems, and also for compiling foreign code (particularly
1904 for use with ASIS). The representation clauses that are ignored
1905 are: enumeration_representation_clause, record_representation_clause,
1906 and attribute_definition_clause for the following attributes:
1907 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1908 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
1909 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
1910 Note that this option should be used only for compiling -- the
1911 code is likely to malfunction at run time.
1913 Note that when :switch:`-gnatct` is used to generate trees for input
1914 into ASIS tools, these representation clauses are removed
1915 from the tree and ignored. This means that the tool will not see them.
1918 .. index:: -gnatjnn (gcc)
1920 :switch:`-gnatj{nn}`
1921 Reformat error messages to fit on ``nn`` character lines
1924 .. index:: -gnatJ (gcc)
1927 Permissive elaboration-checking mode enabled. When this switch is in effect,
1928 the post-18.x access-before-elaboration model ignores potential issues with:
1931 - Activations of tasks defined in instances
1933 - Calls from within an instance to its enclosing context
1934 - Calls through generic formal parameters
1935 - Calls to subprograms defined in instances
1937 - Indirect calls using 'Access
1938 - Requeue statements
1940 - Synchronous task suspension
1942 and does not emit compile-time diagnostics or run-time checks. For further
1943 details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1946 .. index:: -gnatk (gcc)
1948 :switch:`-gnatk={n}`
1949 Limit file names to ``n`` (1-999) characters (``k`` = krunch).
1952 .. index:: -gnatl (gcc)
1955 Output full source listing with embedded error messages.
1958 .. index:: -gnatL (gcc)
1961 Used in conjunction with -gnatG or -gnatD to intersperse original
1962 source lines (as comment lines with line numbers) in the expanded
1966 .. index:: -gnatm (gcc)
1968 :switch:`-gnatm={n}`
1969 Limit number of detected error or warning messages to ``n``
1970 where ``n`` is in the range 1..999999. The default setting if
1971 no switch is given is 9999. If the number of warnings reaches this
1972 limit, then a message is output and further warnings are suppressed,
1973 but the compilation is continued. If the number of error messages
1974 reaches this limit, then a message is output and the compilation
1975 is abandoned. The equal sign here is optional. A value of zero
1976 means that no limit applies.
1979 .. index:: -gnatn (gcc)
1981 :switch:`-gnatn[12]`
1982 Activate inlining across units for subprograms for which pragma ``Inline``
1983 is specified. This inlining is performed by the GCC back-end. An optional
1984 digit sets the inlining level: 1 for moderate inlining across units
1985 or 2 for full inlining across units. If no inlining level is specified,
1986 the compiler will pick it based on the optimization level.
1989 .. index:: -gnatN (gcc)
1992 Activate front end inlining for subprograms for which
1993 pragma ``Inline`` is specified. This inlining is performed
1994 by the front end and will be visible in the
1995 :switch:`-gnatG` output.
1997 When using a gcc-based back end (in practice this means using any version
1998 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
1999 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
2000 Historically front end inlining was more extensive than the gcc back end
2001 inlining, but that is no longer the case.
2004 .. index:: -gnato0 (gcc)
2007 Suppresses overflow checking. This causes the behavior of the compiler to
2008 match the default for older versions where overflow checking was suppressed
2009 by default. This is equivalent to having
2010 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
2013 .. index:: -gnato?? (gcc)
2016 Set default mode for handling generation of code to avoid intermediate
2017 arithmetic overflow. Here ``??`` is two digits, a
2018 single digit, or nothing. Each digit is one of the digits ``1``
2021 ===== ===============================================================
2022 Digit Interpretation
2023 ----- ---------------------------------------------------------------
2024 *1* All intermediate overflows checked against base type (``STRICT``)
2025 *2* Minimize intermediate overflows (``MINIMIZED``)
2026 *3* Eliminate intermediate overflows (``ELIMINATED``)
2027 ===== ===============================================================
2029 If only one digit appears, then it applies to all
2030 cases; if two digits are given, then the first applies outside
2031 assertions, pre/postconditions, and type invariants, and the second
2032 applies within assertions, pre/postconditions, and type invariants.
2034 If no digits follow the :switch:`-gnato`, then it is equivalent to
2036 causing all intermediate overflows to be handled in strict
2039 This switch also causes arithmetic overflow checking to be performed
2040 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
2042 The default if no option :switch:`-gnato` is given is that overflow handling
2043 is in ``STRICT`` mode (computations done using the base type), and that
2044 overflow checking is enabled.
2046 Note that division by zero is a separate check that is not
2047 controlled by this switch (divide-by-zero checking is on by default).
2049 See also :ref:`Specifying_the_Desired_Mode`.
2052 .. index:: -gnatp (gcc)
2055 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
2056 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
2059 .. index:: -gnat-p (gcc)
2062 Cancel effect of previous :switch:`-gnatp` switch.
2065 .. index:: -gnatP (gcc)
2068 Enable polling. This is required on some systems (notably Windows NT) to
2069 obtain asynchronous abort and asynchronous transfer of control capability.
2070 See ``Pragma_Polling`` in the :title:`GNAT_Reference_Manual` for full
2074 .. index:: -gnatq (gcc)
2077 Don't quit. Try semantics, even if parse errors.
2080 .. index:: -gnatQ (gcc)
2083 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2084 Note that code generation is still suppressed in the presence of any
2085 errors, so even with :switch:`-gnatQ` no object file is generated.
2088 .. index:: -gnatr (gcc)
2091 Treat pragma Restrictions as Restriction_Warnings.
2094 .. index:: -gnatR (gcc)
2096 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
2097 Output representation information for declared types, objects and
2098 subprograms. Note that this switch is not allowed if a previous
2099 :switch:`-gnatD` switch has been given, since these two switches
2103 .. index:: -gnats (gcc)
2109 .. index:: -gnatS (gcc)
2112 Print package Standard.
2115 .. index:: -gnatt (gcc)
2118 Generate tree output file.
2121 .. index:: -gnatT (gcc)
2123 :switch:`-gnatT{nnn}`
2124 All compiler tables start at ``nnn`` times usual starting size.
2127 .. index:: -gnatu (gcc)
2130 List units for this compilation.
2133 .. index:: -gnatU (gcc)
2136 Tag all error messages with the unique string 'error:'
2139 .. index:: -gnatv (gcc)
2142 Verbose mode. Full error output with source lines to :file:`stdout`.
2145 .. index:: -gnatV (gcc)
2148 Control level of validity checking (:ref:`Validity_Checking`).
2151 .. index:: -gnatw (gcc)
2153 :switch:`-gnatw{xxx}`
2155 ``xxx`` is a string of option letters that denotes
2156 the exact warnings that
2157 are enabled or disabled (:ref:`Warning_Message_Control`).
2160 .. index:: -gnatW (gcc)
2163 Wide character encoding method
2164 (``e``\ =n/h/u/s/e/8).
2167 .. index:: -gnatx (gcc)
2170 Suppress generation of cross-reference information.
2173 .. index:: -gnatX (gcc)
2176 Enable GNAT implementation extensions and latest Ada version.
2179 .. index:: -gnaty (gcc)
2182 Enable built-in style checks (:ref:`Style_Checking`).
2185 .. index:: -gnatz (gcc)
2188 Distribution stub generation and compilation
2189 (``m``\ =r/c for receiver/caller stubs).
2197 Direct GNAT to search the ``dir`` directory for source files needed by
2198 the current compilation
2199 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2202 .. index:: -I- (gcc)
2207 Except for the source file named in the command line, do not look for source
2208 files in the directory containing the source file named in the command line
2209 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2215 This switch is used in ``gcc`` to redirect the generated object file
2216 and its associated ALI file. Beware of this switch with GNAT, because it may
2217 cause the object file and ALI file to have different names which in turn
2218 may confuse the binder and the linker.
2221 .. index:: -nostdinc (gcc)
2224 Inhibit the search of the default location for the GNAT Run Time
2225 Library (RTL) source files.
2228 .. index:: -nostdlib (gcc)
2231 Inhibit the search of the default location for the GNAT Run Time
2232 Library (RTL) ALI files.
2238 ``n`` controls the optimization level:
2240 ======= ==================================================================
2242 ------- ------------------------------------------------------------------
2243 *0* No optimization, the default setting if no :switch:`-O` appears
2244 *1* Normal optimization, the default if you specify :switch:`-O` without an
2245 operand. A good compromise between code quality and compilation
2247 *2* Extensive optimization, may improve execution time, possibly at
2248 the cost of substantially increased compilation time.
2249 *3* Same as :switch:`-O2`, and also includes inline expansion for small
2250 subprograms in the same unit.
2251 *s* Optimize space usage
2252 ======= ==================================================================
2254 See also :ref:`Optimization_Levels`.
2257 .. index:: -pass-exit-codes (gcc)
2259 :switch:`-pass-exit-codes`
2260 Catch exit codes from the compiler and use the most meaningful as
2264 .. index:: --RTS (gcc)
2266 :switch:`--RTS={rts-path}`
2267 Specifies the default location of the run-time library. Same meaning as the
2268 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
2274 Used in place of :switch:`-c` to
2275 cause the assembler source file to be
2276 generated, using :file:`.s` as the extension,
2277 instead of the object file.
2278 This may be useful if you need to examine the generated assembly code.
2281 .. index:: -fverbose-asm (gcc)
2283 :switch:`-fverbose-asm`
2284 Used in conjunction with :switch:`-S`
2285 to cause the generated assembly code file to be annotated with variable
2286 names, making it significantly easier to follow.
2292 Show commands generated by the ``gcc`` driver. Normally used only for
2293 debugging purposes or if you need to be sure what version of the
2294 compiler you are executing.
2300 Execute ``ver`` version of the compiler. This is the ``gcc``
2301 version, not the GNAT version.
2307 Turn off warnings generated by the back end of the compiler. Use of
2308 this switch also causes the default for front end warnings to be set
2309 to suppress (as though :switch:`-gnatws` had appeared at the start of
2313 .. index:: Combining GNAT switches
2315 You may combine a sequence of GNAT switches into a single switch. For
2316 example, the combined switch
2322 is equivalent to specifying the following sequence of switches:
2326 -gnato -gnatf -gnati3
2328 The following restrictions apply to the combination of switches
2331 * The switch :switch:`-gnatc` if combined with other switches must come
2332 first in the string.
2334 * The switch :switch:`-gnats` if combined with other switches must come
2335 first in the string.
2338 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
2339 switches, and only one of them may appear in the command line.
2341 * The switch :switch:`-gnat-p` may not be combined with any other switch.
2343 * Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
2344 switch), then all further characters in the switch are interpreted
2345 as style modifiers (see description of :switch:`-gnaty`).
2347 * Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
2348 switch), then all further characters in the switch are interpreted
2349 as debug flags (see description of :switch:`-gnatd`).
2351 * Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
2352 switch), then all further characters in the switch are interpreted
2353 as warning mode modifiers (see description of :switch:`-gnatw`).
2355 * Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
2356 switch), then all further characters in the switch are interpreted
2357 as validity checking options (:ref:`Validity_Checking`).
2359 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2360 a combined list of options.
2362 .. _Output_and_Error_Message_Control:
2364 Output and Error Message Control
2365 --------------------------------
2369 The standard default format for error messages is called 'brief format'.
2370 Brief format messages are written to :file:`stderr` (the standard error
2371 file) and have the following form:
2375 e.adb:3:04: Incorrect spelling of keyword "function"
2376 e.adb:4:20: ";" should be "is"
2378 The first integer after the file name is the line number in the file,
2379 and the second integer is the column number within the line.
2380 ``GNAT Studio`` can parse the error messages
2381 and point to the referenced character.
2382 The following switches provide control over the error message
2386 .. index:: -gnatv (gcc)
2389 The ``v`` stands for verbose.
2390 The effect of this setting is to write long-format error
2391 messages to :file:`stdout` (the standard output file.
2392 The same program compiled with the
2393 :switch:`-gnatv` switch would generate:
2397 3. funcion X (Q : Integer)
2399 >>> Incorrect spelling of keyword "function"
2402 >>> ";" should be "is"
2405 The vertical bar indicates the location of the error, and the ``>>>``
2406 prefix can be used to search for error messages. When this switch is
2407 used the only source lines output are those with errors.
2410 .. index:: -gnatl (gcc)
2413 The ``l`` stands for list.
2414 This switch causes a full listing of
2415 the file to be generated. In the case where a body is
2416 compiled, the corresponding spec is also listed, along
2417 with any subunits. Typical output from compiling a package
2418 body :file:`p.adb` might look like::
2422 1. package body p is
2424 3. procedure a is separate;
2435 2. pragma Elaborate_Body
2456 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
2457 standard output is redirected, a brief summary is written to
2458 :file:`stderr` (standard error) giving the number of error messages and
2459 warning messages generated.
2462 .. index:: -gnatl=fname (gcc)
2464 :switch:`-gnatl={fname}`
2465 This has the same effect as :switch:`-gnatl` except that the output is
2466 written to a file instead of to standard output. If the given name
2467 :file:`fname` does not start with a period, then it is the full name
2468 of the file to be written. If :file:`fname` is an extension, it is
2469 appended to the name of the file being compiled. For example, if
2470 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
2471 then the output is written to file xyz.adb.lst.
2474 .. index:: -gnatU (gcc)
2477 This switch forces all error messages to be preceded by the unique
2478 string 'error:'. This means that error messages take a few more
2479 characters in space, but allows easy searching for and identification
2483 .. index:: -gnatb (gcc)
2486 The ``b`` stands for brief.
2487 This switch causes GNAT to generate the
2488 brief format error messages to :file:`stderr` (the standard error
2489 file) as well as the verbose
2490 format message or full listing (which as usual is written to
2491 :file:`stdout` (the standard output file).
2494 .. index:: -gnatm (gcc)
2496 :switch:`-gnatm={n}`
2497 The ``m`` stands for maximum.
2498 ``n`` is a decimal integer in the
2499 range of 1 to 999999 and limits the number of error or warning
2500 messages to be generated. For example, using
2501 :switch:`-gnatm2` might yield
2505 e.adb:3:04: Incorrect spelling of keyword "function"
2506 e.adb:5:35: missing ".."
2507 fatal error: maximum number of errors detected
2508 compilation abandoned
2511 The default setting if
2512 no switch is given is 9999. If the number of warnings reaches this
2513 limit, then a message is output and further warnings are suppressed,
2514 but the compilation is continued. If the number of error messages
2515 reaches this limit, then a message is output and the compilation
2516 is abandoned. A value of zero means that no limit applies.
2518 Note that the equal sign is optional, so the switches
2519 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
2522 .. index:: -gnatf (gcc)
2525 .. index:: Error messages, suppressing
2527 The ``f`` stands for full.
2528 Normally, the compiler suppresses error messages that are likely to be
2529 redundant. This switch causes all error
2530 messages to be generated. In particular, in the case of
2531 references to undefined variables. If a given variable is referenced
2532 several times, the normal format of messages is
2536 e.adb:7:07: "V" is undefined (more references follow)
2538 where the parenthetical comment warns that there are additional
2539 references to the variable ``V``. Compiling the same program with the
2540 :switch:`-gnatf` switch yields
2544 e.adb:7:07: "V" is undefined
2545 e.adb:8:07: "V" is undefined
2546 e.adb:8:12: "V" is undefined
2547 e.adb:8:16: "V" is undefined
2548 e.adb:9:07: "V" is undefined
2549 e.adb:9:12: "V" is undefined
2551 The :switch:`-gnatf` switch also generates additional information for
2552 some error messages. Some examples are:
2554 * Details on possibly non-portable unchecked conversion
2556 * List possible interpretations for ambiguous calls
2558 * Additional details on incorrect parameters
2561 .. index:: -gnatjnn (gcc)
2564 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
2565 with continuation lines are treated as though the continuation lines were
2566 separate messages (and so a warning with two continuation lines counts as
2567 three warnings, and is listed as three separate messages).
2569 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
2570 messages are output in a different manner. A message and all its continuation
2571 lines are treated as a unit, and count as only one warning or message in the
2572 statistics totals. Furthermore, the message is reformatted so that no line
2573 is longer than nn characters.
2576 .. index:: -gnatq (gcc)
2579 The ``q`` stands for quit (really 'don't quit').
2580 In normal operation mode, the compiler first parses the program and
2581 determines if there are any syntax errors. If there are, appropriate
2582 error messages are generated and compilation is immediately terminated.
2584 GNAT to continue with semantic analysis even if syntax errors have been
2585 found. This may enable the detection of more errors in a single run. On
2586 the other hand, the semantic analyzer is more likely to encounter some
2587 internal fatal error when given a syntactically invalid tree.
2590 .. index:: -gnatQ (gcc)
2593 In normal operation mode, the :file:`ALI` file is not generated if any
2594 illegalities are detected in the program. The use of :switch:`-gnatQ` forces
2595 generation of the :file:`ALI` file. This file is marked as being in
2596 error, so it cannot be used for binding purposes, but it does contain
2597 reasonably complete cross-reference information, and thus may be useful
2598 for use by tools (e.g., semantic browsing tools or integrated development
2599 environments) that are driven from the :file:`ALI` file. This switch
2600 implies :switch:`-gnatq`, since the semantic phase must be run to get a
2601 meaningful ALI file.
2603 In addition, if :switch:`-gnatt` is also specified, then the tree file is
2604 generated even if there are illegalities. It may be useful in this case
2605 to also specify :switch:`-gnatq` to ensure that full semantic processing
2606 occurs. The resulting tree file can be processed by ASIS, for the purpose
2607 of providing partial information about illegal units, but if the error
2608 causes the tree to be badly malformed, then ASIS may crash during the
2611 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
2612 being in error, ``gnatmake`` will attempt to recompile the source when it
2613 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
2615 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
2616 since ALI files are never generated if :switch:`-gnats` is set.
2619 .. _Warning_Message_Control:
2621 Warning Message Control
2622 -----------------------
2624 .. index:: Warning messages
2626 In addition to error messages, which correspond to illegalities as defined
2627 in the Ada Reference Manual, the compiler detects two kinds of warning
2630 First, the compiler considers some constructs suspicious and generates a
2631 warning message to alert you to a possible error. Second, if the
2632 compiler detects a situation that is sure to raise an exception at
2633 run time, it generates a warning message. The following shows an example
2634 of warning messages:
2638 e.adb:4:24: warning: creation of object may raise Storage_Error
2639 e.adb:10:17: warning: static value out of range
2640 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2643 GNAT considers a large number of situations as appropriate
2644 for the generation of warning messages. As always, warnings are not
2645 definite indications of errors. For example, if you do an out-of-range
2646 assignment with the deliberate intention of raising a
2647 ``Constraint_Error`` exception, then the warning that may be
2648 issued does not indicate an error. Some of the situations for which GNAT
2649 issues warnings (at least some of the time) are given in the following
2650 list. This list is not complete, and new warnings are often added to
2651 subsequent versions of GNAT. The list is intended to give a general idea
2652 of the kinds of warnings that are generated.
2654 * Possible infinitely recursive calls
2656 * Out-of-range values being assigned
2658 * Possible order of elaboration problems
2660 * Size not a multiple of alignment for a record type
2662 * Assertions (pragma Assert) that are sure to fail
2666 * Address clauses with possibly unaligned values, or where an attempt is
2667 made to overlay a smaller variable with a larger one.
2669 * Fixed-point type declarations with a null range
2671 * Direct_IO or Sequential_IO instantiated with a type that has access values
2673 * Variables that are never assigned a value
2675 * Variables that are referenced before being initialized
2677 * Task entries with no corresponding ``accept`` statement
2679 * Duplicate accepts for the same task entry in a ``select``
2681 * Objects that take too much storage
2683 * Unchecked conversion between types of differing sizes
2685 * Missing ``return`` statement along some execution path in a function
2687 * Incorrect (unrecognized) pragmas
2689 * Incorrect external names
2691 * Allocation from empty storage pool
2693 * Potentially blocking operation in protected type
2695 * Suspicious parenthesization of expressions
2697 * Mismatching bounds in an aggregate
2699 * Attempt to return local value by reference
2701 * Premature instantiation of a generic body
2703 * Attempt to pack aliased components
2705 * Out of bounds array subscripts
2707 * Wrong length on string assignment
2709 * Violations of style rules if style checking is enabled
2711 * Unused |with| clauses
2713 * ``Bit_Order`` usage that does not have any effect
2715 * ``Standard.Duration`` used to resolve universal fixed expression
2717 * Dereference of possibly null value
2719 * Declaration that is likely to cause storage error
2721 * Internal GNAT unit |withed| by application unit
2723 * Values known to be out of range at compile time
2725 * Unreferenced or unmodified variables. Note that a special
2726 exemption applies to variables which contain any of the substrings
2727 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
2728 are considered likely to be intentionally used in a situation where
2729 otherwise a warning would be given, so warnings of this kind are
2730 always suppressed for such variables.
2732 * Address overlays that could clobber memory
2734 * Unexpected initialization when address clause present
2736 * Bad alignment for address clause
2738 * Useless type conversions
2740 * Redundant assignment statements and other redundant constructs
2742 * Useless exception handlers
2744 * Accidental hiding of name by child unit
2746 * Access before elaboration detected at compile time
2748 * A range in a ``for`` loop that is known to be null or might be null
2751 The following section lists compiler switches that are available
2752 to control the handling of warning messages. It is also possible
2753 to exercise much finer control over what warnings are issued and
2754 suppressed using the GNAT pragma Warnings (see the description
2755 of the pragma in the :title:`GNAT_Reference_manual`).
2758 .. index:: -gnatwa (gcc)
2761 *Activate most optional warnings.*
2763 This switch activates most optional warning messages. See the remaining list
2764 in this section for details on optional warning messages that can be
2765 individually controlled. The warnings that are not turned on by this
2769 * :switch:`-gnatwd` (implicit dereferencing)
2771 * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
2773 * :switch:`-gnatwh` (hiding)
2775 * :switch:`-gnatw.h` (holes in record layouts)
2777 * :switch:`-gnatw.j` (late primitives of tagged types)
2779 * :switch:`-gnatw.k` (redefinition of names in standard)
2781 * :switch:`-gnatwl` (elaboration warnings)
2783 * :switch:`-gnatw.l` (inherited aspects)
2785 * :switch:`-gnatw.n` (atomic synchronization)
2787 * :switch:`-gnatwo` (address clause overlay)
2789 * :switch:`-gnatw.o` (values set by out parameters ignored)
2791 * :switch:`-gnatw.q` (questionable layout of record types)
2793 * :switch:`-gnatw_r` (out-of-order record representation clauses)
2795 * :switch:`-gnatw.s` (overridden size clause)
2797 * :switch:`-gnatwt` (tracking of deleted conditional code)
2799 * :switch:`-gnatw.u` (unordered enumeration)
2801 * :switch:`-gnatw.w` (use of Warnings Off)
2803 * :switch:`-gnatw.y` (reasons for package needing body)
2805 All other optional warnings are turned on.
2808 .. index:: -gnatwA (gcc)
2811 *Suppress all optional errors.*
2813 This switch suppresses all optional warning messages, see remaining list
2814 in this section for details on optional warning messages that can be
2815 individually controlled. Note that unlike switch :switch:`-gnatws`, the
2816 use of switch :switch:`-gnatwA` does not suppress warnings that are
2817 normally given unconditionally and cannot be individually controlled
2818 (for example, the warning about a missing exit path in a function).
2819 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
2820 the use of switch :switch:`-gnatwA` can be individually turned back
2821 on. For example the use of switch :switch:`-gnatwA` followed by
2822 switch :switch:`-gnatwd` will suppress all optional warnings except
2823 the warnings for implicit dereferencing.
2825 .. index:: -gnatw.a (gcc)
2828 *Activate warnings on failing assertions.*
2830 .. index:: Assert failures
2832 This switch activates warnings for assertions where the compiler can tell at
2833 compile time that the assertion will fail. Note that this warning is given
2834 even if assertions are disabled. The default is that such warnings are
2838 .. index:: -gnatw.A (gcc)
2841 *Suppress warnings on failing assertions.*
2843 .. index:: Assert failures
2845 This switch suppresses warnings for assertions where the compiler can tell at
2846 compile time that the assertion will fail.
2852 *Activate warnings on anonymous allocators.*
2854 .. index:: Anonymous allocators
2856 This switch activates warnings for allocators of anonymous access types,
2857 which can involve run-time accessibility checks and lead to unexpected
2858 accessibility violations. For more details on the rules involved, see
2865 *Supress warnings on anonymous allocators.*
2867 .. index:: Anonymous allocators
2869 This switch suppresses warnings for anonymous access type allocators.
2872 .. index:: -gnatwb (gcc)
2875 *Activate warnings on bad fixed values.*
2877 .. index:: Bad fixed values
2879 .. index:: Fixed-point Small value
2881 .. index:: Small value
2883 This switch activates warnings for static fixed-point expressions whose
2884 value is not an exact multiple of Small. Such values are implementation
2885 dependent, since an implementation is free to choose either of the multiples
2886 that surround the value. GNAT always chooses the closer one, but this is not
2887 required behavior, and it is better to specify a value that is an exact
2888 multiple, ensuring predictable execution. The default is that such warnings
2892 .. index:: -gnatwB (gcc)
2895 *Suppress warnings on bad fixed values.*
2897 This switch suppresses warnings for static fixed-point expressions whose
2898 value is not an exact multiple of Small.
2901 .. index:: -gnatw.b (gcc)
2904 *Activate warnings on biased representation.*
2906 .. index:: Biased representation
2908 This switch activates warnings when a size clause, value size clause, component
2909 clause, or component size clause forces the use of biased representation for an
2910 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2911 to represent 10/11). The default is that such warnings are generated.
2914 .. index:: -gnatwB (gcc)
2917 *Suppress warnings on biased representation.*
2919 This switch suppresses warnings for representation clauses that force the use
2920 of biased representation.
2923 .. index:: -gnatwc (gcc)
2926 *Activate warnings on conditionals.*
2928 .. index:: Conditionals, constant
2930 This switch activates warnings for conditional expressions used in
2931 tests that are known to be True or False at compile time. The default
2932 is that such warnings are not generated.
2933 Note that this warning does
2934 not get issued for the use of boolean variables or constants whose
2935 values are known at compile time, since this is a standard technique
2936 for conditional compilation in Ada, and this would generate too many
2937 false positive warnings.
2939 This warning option also activates a special test for comparisons using
2940 the operators '>=' and' <='.
2941 If the compiler can tell that only the equality condition is possible,
2942 then it will warn that the '>' or '<' part of the test
2943 is useless and that the operator could be replaced by '='.
2944 An example would be comparing a ``Natural`` variable <= 0.
2946 This warning option also generates warnings if
2947 one or both tests is optimized away in a membership test for integer
2948 values if the result can be determined at compile time. Range tests on
2949 enumeration types are not included, since it is common for such tests
2950 to include an end point.
2952 This warning can also be turned on using :switch:`-gnatwa`.
2955 .. index:: -gnatwC (gcc)
2958 *Suppress warnings on conditionals.*
2960 This switch suppresses warnings for conditional expressions used in
2961 tests that are known to be True or False at compile time.
2964 .. index:: -gnatw.c (gcc)
2967 *Activate warnings on missing component clauses.*
2969 .. index:: Component clause, missing
2971 This switch activates warnings for record components where a record
2972 representation clause is present and has component clauses for the
2973 majority, but not all, of the components. A warning is given for each
2974 component for which no component clause is present.
2977 .. index:: -gnatw.C (gcc)
2980 *Suppress warnings on missing component clauses.*
2982 This switch suppresses warnings for record components that are
2983 missing a component clause in the situation described above.
2986 .. index:: -gnatw_c (gcc)
2989 *Activate warnings on unknown condition in Compile_Time_Warning.*
2991 .. index:: Compile_Time_Warning
2992 .. index:: Compile_Time_Error
2994 This switch activates warnings on a pragma Compile_Time_Warning
2995 or Compile_Time_Error whose condition has a value that is not
2996 known at compile time.
2997 The default is that such warnings are generated.
3000 .. index:: -gnatw_C (gcc)
3003 *Suppress warnings on unknown condition in Compile_Time_Warning.*
3005 This switch supresses warnings on a pragma Compile_Time_Warning
3006 or Compile_Time_Error whose condition has a value that is not
3007 known at compile time.
3010 .. index:: -gnatwd (gcc)
3013 *Activate warnings on implicit dereferencing.*
3015 If this switch is set, then the use of a prefix of an access type
3016 in an indexed component, slice, or selected component without an
3017 explicit ``.all`` will generate a warning. With this warning
3018 enabled, access checks occur only at points where an explicit
3019 ``.all`` appears in the source code (assuming no warnings are
3020 generated as a result of this switch). The default is that such
3021 warnings are not generated.
3024 .. index:: -gnatwD (gcc)
3027 *Suppress warnings on implicit dereferencing.*
3029 .. index:: Implicit dereferencing
3031 .. index:: Dereferencing, implicit
3033 This switch suppresses warnings for implicit dereferences in
3034 indexed components, slices, and selected components.
3037 .. index:: -gnatw.d (gcc)
3040 *Activate tagging of warning and info messages.*
3042 If this switch is set, then warning messages are tagged, with one of the
3046 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
3051 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
3056 Used to tag elaboration information (info) messages generated when the
3057 static model of elaboration is used and the :switch:`-gnatel` switch is set.
3060 - *[restriction warning]*
3061 Used to tag warning messages for restriction violations, activated by use
3062 of the pragma ``Restriction_Warnings``.
3065 - *[warning-as-error]*
3066 Used to tag warning messages that have been converted to error messages by
3067 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
3068 the string "error: " rather than "warning: ".
3071 - *[enabled by default]*
3072 Used to tag all other warnings that are always given by default, unless
3073 warnings are completely suppressed using pragma *Warnings(Off)* or
3074 the switch :switch:`-gnatws`.
3078 .. index:: -gnatw.d (gcc)
3081 *Deactivate tagging of warning and info messages messages.*
3083 If this switch is set, then warning messages return to the default
3084 mode in which warnings and info messages are not tagged as described above for
3088 .. index:: -gnatwe (gcc)
3089 .. index:: Warnings, treat as error
3092 *Treat warnings and style checks as errors.*
3094 This switch causes warning messages and style check messages to be
3096 The warning string still appears, but the warning messages are counted
3097 as errors, and prevent the generation of an object file. Note that this
3098 is the only -gnatw switch that affects the handling of style check messages.
3099 Note also that this switch has no effect on info (information) messages, which
3100 are not treated as errors if this switch is present.
3103 .. index:: -gnatw.e (gcc)
3106 *Activate every optional warning.*
3108 .. index:: Warnings, activate every optional warning
3110 This switch activates all optional warnings, including those which
3111 are not activated by :switch:`-gnatwa`. The use of this switch is not
3112 recommended for normal use. If you turn this switch on, it is almost
3113 certain that you will get large numbers of useless warnings. The
3114 warnings that are excluded from :switch:`-gnatwa` are typically highly
3115 specialized warnings that are suitable for use only in code that has
3116 been specifically designed according to specialized coding rules.
3119 .. index:: -gnatwE (gcc)
3120 .. index:: Warnings, treat as error
3123 *Treat all run-time exception warnings as errors.*
3125 This switch causes warning messages regarding errors that will be raised
3126 during run-time execution to be treated as errors.
3129 .. index:: -gnatwf (gcc)
3132 *Activate warnings on unreferenced formals.*
3134 .. index:: Formals, unreferenced
3136 This switch causes a warning to be generated if a formal parameter
3137 is not referenced in the body of the subprogram. This warning can
3138 also be turned on using :switch:`-gnatwu`. The
3139 default is that these warnings are not generated.
3142 .. index:: -gnatwF (gcc)
3145 *Suppress warnings on unreferenced formals.*
3147 This switch suppresses warnings for unreferenced formal
3148 parameters. Note that the
3149 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
3150 effect of warning on unreferenced entities other than subprogram
3154 .. index:: -gnatwg (gcc)
3157 *Activate warnings on unrecognized pragmas.*
3159 .. index:: Pragmas, unrecognized
3161 This switch causes a warning to be generated if an unrecognized
3162 pragma is encountered. Apart from issuing this warning, the
3163 pragma is ignored and has no effect. The default
3164 is that such warnings are issued (satisfying the Ada Reference
3165 Manual requirement that such warnings appear).
3168 .. index:: -gnatwG (gcc)
3171 *Suppress warnings on unrecognized pragmas.*
3173 This switch suppresses warnings for unrecognized pragmas.
3176 .. index:: -gnatw.g (gcc)
3179 *Warnings used for GNAT sources.*
3181 This switch sets the warning categories that are used by the standard
3182 GNAT style. Currently this is equivalent to
3183 :switch:`-gnatwAao.q.s.CI.V.X.Z`
3184 but more warnings may be added in the future without advanced notice.
3187 .. index:: -gnatwh (gcc)
3190 *Activate warnings on hiding.*
3192 .. index:: Hiding of Declarations
3194 This switch activates warnings on hiding declarations that are considered
3195 potentially confusing. Not all cases of hiding cause warnings; for example an
3196 overriding declaration hides an implicit declaration, which is just normal
3197 code. The default is that warnings on hiding are not generated.
3200 .. index:: -gnatwH (gcc)
3203 *Suppress warnings on hiding.*
3205 This switch suppresses warnings on hiding declarations.
3208 .. index:: -gnatw.h (gcc)
3211 *Activate warnings on holes/gaps in records.*
3213 .. index:: Record Representation (gaps)
3215 This switch activates warnings on component clauses in record
3216 representation clauses that leave holes (gaps) in the record layout.
3217 If this warning option is active, then record representation clauses
3218 should specify a contiguous layout, adding unused fill fields if needed.
3221 .. index:: -gnatw.H (gcc)
3224 *Suppress warnings on holes/gaps in records.*
3226 This switch suppresses warnings on component clauses in record
3227 representation clauses that leave holes (haps) in the record layout.
3230 .. index:: -gnatwi (gcc)
3233 *Activate warnings on implementation units.*
3235 This switch activates warnings for a |with| of an internal GNAT
3236 implementation unit, defined as any unit from the ``Ada``,
3237 ``Interfaces``, ``GNAT``,
3239 hierarchies that is not
3240 documented in either the Ada Reference Manual or the GNAT
3241 Programmer's Reference Manual. Such units are intended only
3242 for internal implementation purposes and should not be |withed|
3243 by user programs. The default is that such warnings are generated
3246 .. index:: -gnatwI (gcc)
3249 *Disable warnings on implementation units.*
3251 This switch disables warnings for a |with| of an internal GNAT
3252 implementation unit.
3255 .. index:: -gnatw.i (gcc)
3258 *Activate warnings on overlapping actuals.*
3260 This switch enables a warning on statically detectable overlapping actuals in
3261 a subprogram call, when one of the actuals is an in-out parameter, and the
3262 types of the actuals are not by-copy types. This warning is off by default.
3265 .. index:: -gnatw.I (gcc)
3268 *Disable warnings on overlapping actuals.*
3270 This switch disables warnings on overlapping actuals in a call..
3273 .. index:: -gnatwj (gcc)
3276 *Activate warnings on obsolescent features (Annex J).*
3278 .. index:: Features, obsolescent
3280 .. index:: Obsolescent features
3282 If this warning option is activated, then warnings are generated for
3283 calls to subprograms marked with ``pragma Obsolescent`` and
3284 for use of features in Annex J of the Ada Reference Manual. In the
3285 case of Annex J, not all features are flagged. In particular use
3286 of the renamed packages (like ``Text_IO``) and use of package
3287 ``ASCII`` are not flagged, since these are very common and
3288 would generate many annoying positive warnings. The default is that
3289 such warnings are not generated.
3291 In addition to the above cases, warnings are also generated for
3292 GNAT features that have been provided in past versions but which
3293 have been superseded (typically by features in the new Ada standard).
3294 For example, ``pragma Ravenscar`` will be flagged since its
3295 function is replaced by ``pragma Profile(Ravenscar)``, and
3296 ``pragma Interface_Name`` will be flagged since its function
3297 is replaced by ``pragma Import``.
3299 Note that this warning option functions differently from the
3300 restriction ``No_Obsolescent_Features`` in two respects.
3301 First, the restriction applies only to annex J features.
3302 Second, the restriction does flag uses of package ``ASCII``.
3305 .. index:: -gnatwJ (gcc)
3308 *Suppress warnings on obsolescent features (Annex J).*
3310 This switch disables warnings on use of obsolescent features.
3313 .. index:: -gnatw.j (gcc)
3316 *Activate warnings on late declarations of tagged type primitives.*
3318 This switch activates warnings on visible primitives added to a
3319 tagged type after deriving a private extension from it.
3322 .. index:: -gnatw.J (gcc)
3325 *Suppress warnings on late declarations of tagged type primitives.*
3327 This switch suppresses warnings on visible primitives added to a
3328 tagged type after deriving a private extension from it.
3331 .. index:: -gnatwk (gcc)
3334 *Activate warnings on variables that could be constants.*
3336 This switch activates warnings for variables that are initialized but
3337 never modified, and then could be declared constants. The default is that
3338 such warnings are not given.
3341 .. index:: -gnatwK (gcc)
3344 *Suppress warnings on variables that could be constants.*
3346 This switch disables warnings on variables that could be declared constants.
3349 .. index:: -gnatw.k (gcc)
3352 *Activate warnings on redefinition of names in standard.*
3354 This switch activates warnings for declarations that declare a name that
3355 is defined in package Standard. Such declarations can be confusing,
3356 especially since the names in package Standard continue to be directly
3357 visible, meaning that use visibiliy on such redeclared names does not
3358 work as expected. Names of discriminants and components in records are
3359 not included in this check.
3362 .. index:: -gnatwK (gcc)
3365 *Suppress warnings on redefinition of names in standard.*
3367 This switch activates warnings for declarations that declare a name that
3368 is defined in package Standard.
3371 .. index:: -gnatwl (gcc)
3374 *Activate warnings for elaboration pragmas.*
3376 .. index:: Elaboration, warnings
3378 This switch activates warnings for possible elaboration problems,
3379 including suspicious use
3380 of ``Elaborate`` pragmas, when using the static elaboration model, and
3381 possible situations that may raise ``Program_Error`` when using the
3382 dynamic elaboration model.
3383 See the section in this guide on elaboration checking for further details.
3384 The default is that such warnings
3388 .. index:: -gnatwL (gcc)
3391 *Suppress warnings for elaboration pragmas.*
3393 This switch suppresses warnings for possible elaboration problems.
3396 .. index:: -gnatw.l (gcc)
3399 *List inherited aspects.*
3401 This switch causes the compiler to list inherited invariants,
3402 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3403 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3406 .. index:: -gnatw.L (gcc)
3409 *Suppress listing of inherited aspects.*
3411 This switch suppresses listing of inherited aspects.
3414 .. index:: -gnatwm (gcc)
3417 *Activate warnings on modified but unreferenced variables.*
3419 This switch activates warnings for variables that are assigned (using
3420 an initialization value or with one or more assignment statements) but
3421 whose value is never read. The warning is suppressed for volatile
3422 variables and also for variables that are renamings of other variables
3423 or for which an address clause is given.
3424 The default is that these warnings are not given.
3427 .. index:: -gnatwM (gcc)
3430 *Disable warnings on modified but unreferenced variables.*
3432 This switch disables warnings for variables that are assigned or
3433 initialized, but never read.
3436 .. index:: -gnatw.m (gcc)
3439 *Activate warnings on suspicious modulus values.*
3441 This switch activates warnings for modulus values that seem suspicious.
3442 The cases caught are where the size is the same as the modulus (e.g.
3443 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3444 with no size clause. The guess in both cases is that 2**x was intended
3445 rather than x. In addition expressions of the form 2*x for small x
3446 generate a warning (the almost certainly accurate guess being that
3447 2**x was intended). The default is that these warnings are given.
3450 .. index:: -gnatw.M (gcc)
3453 *Disable warnings on suspicious modulus values.*
3455 This switch disables warnings for suspicious modulus values.
3458 .. index:: -gnatwn (gcc)
3461 *Set normal warnings mode.*
3463 This switch sets normal warning mode, in which enabled warnings are
3464 issued and treated as warnings rather than errors. This is the default
3465 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
3466 an explicit :switch:`-gnatws` or
3467 :switch:`-gnatwe`. It also cancels the effect of the
3468 implicit :switch:`-gnatwe` that is activated by the
3469 use of :switch:`-gnatg`.
3472 .. index:: -gnatw.n (gcc)
3473 .. index:: Atomic Synchronization, warnings
3476 *Activate warnings on atomic synchronization.*
3478 This switch actives warnings when an access to an atomic variable
3479 requires the generation of atomic synchronization code. These
3480 warnings are off by default.
3482 .. index:: -gnatw.N (gcc)
3485 *Suppress warnings on atomic synchronization.*
3487 .. index:: Atomic Synchronization, warnings
3489 This switch suppresses warnings when an access to an atomic variable
3490 requires the generation of atomic synchronization code.
3493 .. index:: -gnatwo (gcc)
3494 .. index:: Address Clauses, warnings
3497 *Activate warnings on address clause overlays.*
3499 This switch activates warnings for possibly unintended initialization
3500 effects of defining address clauses that cause one variable to overlap
3501 another. The default is that such warnings are generated.
3504 .. index:: -gnatwO (gcc)
3507 *Suppress warnings on address clause overlays.*
3509 This switch suppresses warnings on possibly unintended initialization
3510 effects of defining address clauses that cause one variable to overlap
3514 .. index:: -gnatw.o (gcc)
3517 *Activate warnings on modified but unreferenced out parameters.*
3519 This switch activates warnings for variables that are modified by using
3520 them as actuals for a call to a procedure with an out mode formal, where
3521 the resulting assigned value is never read. It is applicable in the case
3522 where there is more than one out mode formal. If there is only one out
3523 mode formal, the warning is issued by default (controlled by -gnatwu).
3524 The warning is suppressed for volatile
3525 variables and also for variables that are renamings of other variables
3526 or for which an address clause is given.
3527 The default is that these warnings are not given.
3530 .. index:: -gnatw.O (gcc)
3533 *Disable warnings on modified but unreferenced out parameters.*
3535 This switch suppresses warnings for variables that are modified by using
3536 them as actuals for a call to a procedure with an out mode formal, where
3537 the resulting assigned value is never read.
3540 .. index:: -gnatwp (gcc)
3541 .. index:: Inlining, warnings
3544 *Activate warnings on ineffective pragma Inlines.*
3546 This switch activates warnings for failure of front end inlining
3547 (activated by :switch:`-gnatN`) to inline a particular call. There are
3548 many reasons for not being able to inline a call, including most
3549 commonly that the call is too complex to inline. The default is
3550 that such warnings are not given.
3551 Warnings on ineffective inlining by the gcc back-end can be activated
3552 separately, using the gcc switch -Winline.
3555 .. index:: -gnatwP (gcc)
3558 *Suppress warnings on ineffective pragma Inlines.*
3560 This switch suppresses warnings on ineffective pragma Inlines. If the
3561 inlining mechanism cannot inline a call, it will simply ignore the
3565 .. index:: -gnatw.p (gcc)
3566 .. index:: Parameter order, warnings
3569 *Activate warnings on parameter ordering.*
3571 This switch activates warnings for cases of suspicious parameter
3572 ordering when the list of arguments are all simple identifiers that
3573 match the names of the formals, but are in a different order. The
3574 warning is suppressed if any use of named parameter notation is used,
3575 so this is the appropriate way to suppress a false positive (and
3576 serves to emphasize that the "misordering" is deliberate). The
3577 default is that such warnings are not given.
3580 .. index:: -gnatw.P (gcc)
3583 *Suppress warnings on parameter ordering.*
3585 This switch suppresses warnings on cases of suspicious parameter
3589 .. index:: -gnatwq (gcc)
3590 .. index:: Parentheses, warnings
3593 *Activate warnings on questionable missing parentheses.*
3595 This switch activates warnings for cases where parentheses are not used and
3596 the result is potential ambiguity from a readers point of view. For example
3597 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3598 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3599 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3600 follow the rule of always parenthesizing to make the association clear, and
3601 this warning switch warns if such parentheses are not present. The default
3602 is that these warnings are given.
3605 .. index:: -gnatwQ (gcc)
3608 *Suppress warnings on questionable missing parentheses.*
3610 This switch suppresses warnings for cases where the association is not
3611 clear and the use of parentheses is preferred.
3614 .. index:: -gnatw.q (gcc)
3615 .. index:: Layout, warnings
3618 *Activate warnings on questionable layout of record types.*
3620 This switch activates warnings for cases where the default layout of
3621 a record type, that is to say the layout of its components in textual
3622 order of the source code, would very likely cause inefficiencies in
3623 the code generated by the compiler, both in terms of space and speed
3624 during execution. One warning is issued for each problematic component
3625 without representation clause in the nonvariant part and then in each
3626 variant recursively, if any.
3628 The purpose of these warnings is neither to prescribe an optimal layout
3629 nor to force the use of representation clauses, but rather to get rid of
3630 the most blatant inefficiencies in the layout. Therefore, the default
3631 layout is matched against the following synthetic ordered layout and
3632 the deviations are flagged on a component-by-component basis:
3634 * first all components or groups of components whose length is fixed
3635 and a multiple of the storage unit,
3637 * then the remaining components whose length is fixed and not a multiple
3638 of the storage unit,
3640 * then the remaining components whose length doesn't depend on discriminants
3641 (that is to say, with variable but uniform length for all objects),
3643 * then all components whose length depends on discriminants,
3645 * finally the variant part (if any),
3647 for the nonvariant part and for each variant recursively, if any.
3649 The exact wording of the warning depends on whether the compiler is allowed
3650 to reorder the components in the record type or precluded from doing it by
3651 means of pragma ``No_Component_Reordering``.
3653 The default is that these warnings are not given.
3655 .. index:: -gnatw.Q (gcc)
3658 *Suppress warnings on questionable layout of record types.*
3660 This switch suppresses warnings for cases where the default layout of
3661 a record type would very likely cause inefficiencies.
3664 .. index:: -gnatwr (gcc)
3667 *Activate warnings on redundant constructs.*
3669 This switch activates warnings for redundant constructs. The following
3670 is the current list of constructs regarded as redundant:
3672 * Assignment of an item to itself.
3674 * Type conversion that converts an expression to its own type.
3676 * Use of the attribute ``Base`` where ``typ'Base`` is the same
3679 * Use of pragma ``Pack`` when all components are placed by a record
3680 representation clause.
3682 * Exception handler containing only a reraise statement (raise with no
3683 operand) which has no effect.
3685 * Use of the operator abs on an operand that is known at compile time
3688 * Comparison of an object or (unary or binary) operation of boolean type to
3689 an explicit True value.
3691 The default is that warnings for redundant constructs are not given.
3694 .. index:: -gnatwR (gcc)
3697 *Suppress warnings on redundant constructs.*
3699 This switch suppresses warnings for redundant constructs.
3702 .. index:: -gnatw.r (gcc)
3705 *Activate warnings for object renaming function.*
3707 This switch activates warnings for an object renaming that renames a
3708 function call, which is equivalent to a constant declaration (as
3709 opposed to renaming the function itself). The default is that these
3713 .. index:: -gnatw.R (gcc)
3716 *Suppress warnings for object renaming function.*
3718 This switch suppresses warnings for object renaming function.
3721 .. index:: -gnatw_r (gcc)
3724 *Activate warnings for out-of-order record representation clauses.*
3726 This switch activates warnings for record representation clauses,
3727 if the order of component declarations, component clauses,
3728 and bit-level layout do not all agree.
3729 The default is that these warnings are not given.
3732 .. index:: -gnatw_R (gcc)
3735 *Suppress warnings for out-of-order record representation clauses.*
3738 .. index:: -gnatws (gcc)
3741 *Suppress all warnings.*
3743 This switch completely suppresses the
3744 output of all warning messages from the GNAT front end, including
3745 both warnings that can be controlled by switches described in this
3746 section, and those that are normally given unconditionally. The
3747 effect of this suppress action can only be cancelled by a subsequent
3748 use of the switch :switch:`-gnatwn`.
3750 Note that switch :switch:`-gnatws` does not suppress
3751 warnings from the ``gcc`` back end.
3752 To suppress these back end warnings as well, use the switch :switch:`-w`
3753 in addition to :switch:`-gnatws`. Also this switch has no effect on the
3754 handling of style check messages.
3757 .. index:: -gnatw.s (gcc)
3758 .. index:: Record Representation (component sizes)
3761 *Activate warnings on overridden size clauses.*
3763 This switch activates warnings on component clauses in record
3764 representation clauses where the length given overrides that
3765 specified by an explicit size clause for the component type. A
3766 warning is similarly given in the array case if a specified
3767 component size overrides an explicit size clause for the array
3771 .. index:: -gnatw.S (gcc)
3774 *Suppress warnings on overridden size clauses.*
3776 This switch suppresses warnings on component clauses in record
3777 representation clauses that override size clauses, and similar
3778 warnings when an array component size overrides a size clause.
3781 .. index:: -gnatwt (gcc)
3782 .. index:: Deactivated code, warnings
3783 .. index:: Deleted code, warnings
3786 *Activate warnings for tracking of deleted conditional code.*
3788 This switch activates warnings for tracking of code in conditionals (IF and
3789 CASE statements) that is detected to be dead code which cannot be executed, and
3790 which is removed by the front end. This warning is off by default. This may be
3791 useful for detecting deactivated code in certified applications.
3794 .. index:: -gnatwT (gcc)
3797 *Suppress warnings for tracking of deleted conditional code.*
3799 This switch suppresses warnings for tracking of deleted conditional code.
3802 .. index:: -gnatw.t (gcc)
3805 *Activate warnings on suspicious contracts.*
3807 This switch activates warnings on suspicious contracts. This includes
3808 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
3809 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3810 ``Contract_Cases``). A function postcondition or contract case is suspicious
3811 when no postcondition or contract case for this function mentions the result
3812 of the function. A procedure postcondition or contract case is suspicious
3813 when it only refers to the pre-state of the procedure, because in that case
3814 it should rather be expressed as a precondition. This switch also controls
3815 warnings on suspicious cases of expressions typically found in contracts like
3816 quantified expressions and uses of Update attribute. The default is that such
3817 warnings are generated.
3820 .. index:: -gnatw.T (gcc)
3823 *Suppress warnings on suspicious contracts.*
3825 This switch suppresses warnings on suspicious contracts.
3828 .. index:: -gnatwu (gcc)
3831 *Activate warnings on unused entities.*
3833 This switch activates warnings to be generated for entities that
3834 are declared but not referenced, and for units that are |withed|
3836 referenced. In the case of packages, a warning is also generated if
3837 no entities in the package are referenced. This means that if a with'ed
3838 package is referenced but the only references are in ``use``
3839 clauses or ``renames``
3840 declarations, a warning is still generated. A warning is also generated
3841 for a generic package that is |withed| but never instantiated.
3842 In the case where a package or subprogram body is compiled, and there
3843 is a |with| on the corresponding spec
3844 that is only referenced in the body,
3845 a warning is also generated, noting that the
3846 |with| can be moved to the body. The default is that
3847 such warnings are not generated.
3848 This switch also activates warnings on unreferenced formals
3849 (it includes the effect of :switch:`-gnatwf`).
3852 .. index:: -gnatwU (gcc)
3855 *Suppress warnings on unused entities.*
3857 This switch suppresses warnings for unused entities and packages.
3858 It also turns off warnings on unreferenced formals (and thus includes
3859 the effect of :switch:`-gnatwF`).
3862 .. index:: -gnatw.u (gcc)
3865 *Activate warnings on unordered enumeration types.*
3867 This switch causes enumeration types to be considered as conceptually
3868 unordered, unless an explicit pragma ``Ordered`` is given for the type.
3869 The effect is to generate warnings in clients that use explicit comparisons
3870 or subranges, since these constructs both treat objects of the type as
3871 ordered. (A *client* is defined as a unit that is other than the unit in
3872 which the type is declared, or its body or subunits.) Please refer to
3873 the description of pragma ``Ordered`` in the
3874 :title:`GNAT Reference Manual` for further details.
3875 The default is that such warnings are not generated.
3878 .. index:: -gnatw.U (gcc)
3881 *Deactivate warnings on unordered enumeration types.*
3883 This switch causes all enumeration types to be considered as ordered, so
3884 that no warnings are given for comparisons or subranges for any type.
3887 .. index:: -gnatwv (gcc)
3888 .. index:: Unassigned variable warnings
3891 *Activate warnings on unassigned variables.*
3893 This switch activates warnings for access to variables which
3894 may not be properly initialized. The default is that
3895 such warnings are generated.
3898 .. index:: -gnatwV (gcc)
3901 *Suppress warnings on unassigned variables.*
3903 This switch suppresses warnings for access to variables which
3904 may not be properly initialized.
3905 For variables of a composite type, the warning can also be suppressed in
3906 Ada 2005 by using a default initialization with a box. For example, if
3907 Table is an array of records whose components are only partially uninitialized,
3908 then the following code:
3912 Tab : Table := (others => <>);
3914 will suppress warnings on subsequent statements that access components
3918 .. index:: -gnatw.v (gcc)
3919 .. index:: bit order warnings
3922 *Activate info messages for non-default bit order.*
3924 This switch activates messages (labeled "info", they are not warnings,
3925 just informational messages) about the effects of non-default bit-order
3926 on records to which a component clause is applied. The effect of specifying
3927 non-default bit ordering is a bit subtle (and changed with Ada 2005), so
3928 these messages, which are given by default, are useful in understanding the
3929 exact consequences of using this feature.
3932 .. index:: -gnatw.V (gcc)
3935 *Suppress info messages for non-default bit order.*
3937 This switch suppresses information messages for the effects of specifying
3938 non-default bit order on record components with component clauses.
3941 .. index:: -gnatww (gcc)
3942 .. index:: String indexing warnings
3945 *Activate warnings on wrong low bound assumption.*
3947 This switch activates warnings for indexing an unconstrained string parameter
3948 with a literal or S'Length. This is a case where the code is assuming that the
3949 low bound is one, which is in general not true (for example when a slice is
3950 passed). The default is that such warnings are generated.
3953 .. index:: -gnatwW (gcc)
3956 *Suppress warnings on wrong low bound assumption.*
3958 This switch suppresses warnings for indexing an unconstrained string parameter
3959 with a literal or S'Length. Note that this warning can also be suppressed
3960 in a particular case by adding an assertion that the lower bound is 1,
3961 as shown in the following example:
3965 procedure K (S : String) is
3966 pragma Assert (S'First = 1);
3970 .. index:: -gnatw.w (gcc)
3971 .. index:: Warnings Off control
3974 *Activate warnings on Warnings Off pragmas.*
3976 This switch activates warnings for use of ``pragma Warnings (Off, entity)``
3977 where either the pragma is entirely useless (because it suppresses no
3978 warnings), or it could be replaced by ``pragma Unreferenced`` or
3979 ``pragma Unmodified``.
3980 Also activates warnings for the case of
3981 Warnings (Off, String), where either there is no matching
3982 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
3983 The default is that these warnings are not given.
3986 .. index:: -gnatw.W (gcc)
3989 *Suppress warnings on unnecessary Warnings Off pragmas.*
3991 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
3994 .. index:: -gnatwx (gcc)
3995 .. index:: Export/Import pragma warnings
3998 *Activate warnings on Export/Import pragmas.*
4000 This switch activates warnings on Export/Import pragmas when
4001 the compiler detects a possible conflict between the Ada and
4002 foreign language calling sequences. For example, the use of
4003 default parameters in a convention C procedure is dubious
4004 because the C compiler cannot supply the proper default, so
4005 a warning is issued. The default is that such warnings are
4009 .. index:: -gnatwX (gcc)
4012 *Suppress warnings on Export/Import pragmas.*
4014 This switch suppresses warnings on Export/Import pragmas.
4015 The sense of this is that you are telling the compiler that
4016 you know what you are doing in writing the pragma, and it
4017 should not complain at you.
4020 .. index:: -gnatwm (gcc)
4023 *Activate warnings for No_Exception_Propagation mode.*
4025 This switch activates warnings for exception usage when pragma Restrictions
4026 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
4027 explicit exception raises which are not covered by a local handler, and for
4028 exception handlers which do not cover a local raise. The default is that
4029 these warnings are given for units that contain exception handlers.
4033 *Disable warnings for No_Exception_Propagation mode.*
4035 This switch disables warnings for exception usage when pragma Restrictions
4036 (No_Exception_Propagation) is in effect.
4039 .. index:: -gnatwy (gcc)
4040 .. index:: Ada compatibility issues warnings
4043 *Activate warnings for Ada compatibility issues.*
4045 For the most part, newer versions of Ada are upwards compatible
4046 with older versions. For example, Ada 2005 programs will almost
4047 always work when compiled as Ada 2012.
4048 However there are some exceptions (for example the fact that
4049 ``some`` is now a reserved word in Ada 2012). This
4050 switch activates several warnings to help in identifying
4051 and correcting such incompatibilities. The default is that
4052 these warnings are generated. Note that at one point Ada 2005
4053 was called Ada 0Y, hence the choice of character.
4056 .. index:: -gnatwY (gcc)
4057 .. index:: Ada compatibility issues warnings
4060 *Disable warnings for Ada compatibility issues.*
4062 This switch suppresses the warnings intended to help in identifying
4063 incompatibilities between Ada language versions.
4066 .. index:: -gnatw.y (gcc)
4067 .. index:: Package spec needing body
4070 *Activate information messages for why package spec needs body.*
4072 There are a number of cases in which a package spec needs a body.
4073 For example, the use of pragma Elaborate_Body, or the declaration
4074 of a procedure specification requiring a completion. This switch
4075 causes information messages to be output showing why a package
4076 specification requires a body. This can be useful in the case of
4077 a large package specification which is unexpectedly requiring a
4078 body. The default is that such information messages are not output.
4081 .. index:: -gnatw.Y (gcc)
4082 .. index:: No information messages for why package spec needs body
4085 *Disable information messages for why package spec needs body.*
4087 This switch suppresses the output of information messages showing why
4088 a package specification needs a body.
4091 .. index:: -gnatwz (gcc)
4092 .. index:: Unchecked_Conversion warnings
4095 *Activate warnings on unchecked conversions.*
4097 This switch activates warnings for unchecked conversions
4098 where the types are known at compile time to have different
4099 sizes. The default is that such warnings are generated. Warnings are also
4100 generated for subprogram pointers with different conventions.
4103 .. index:: -gnatwZ (gcc)
4106 *Suppress warnings on unchecked conversions.*
4108 This switch suppresses warnings for unchecked conversions
4109 where the types are known at compile time to have different
4110 sizes or conventions.
4113 .. index:: -gnatw.z (gcc)
4114 .. index:: Size/Alignment warnings
4117 *Activate warnings for size not a multiple of alignment.*
4119 This switch activates warnings for cases of array and record types
4120 with specified ``Size`` and ``Alignment`` attributes where the
4121 size is not a multiple of the alignment, resulting in an object
4122 size that is greater than the specified size. The default
4123 is that such warnings are generated.
4126 .. index:: -gnatw.Z (gcc)
4127 .. index:: Size/Alignment warnings
4130 *Suppress warnings for size not a multiple of alignment.*
4132 This switch suppresses warnings for cases of array and record types
4133 with specified ``Size`` and ``Alignment`` attributes where the
4134 size is not a multiple of the alignment, resulting in an object
4135 size that is greater than the specified size. The warning can also
4136 be suppressed by giving an explicit ``Object_Size`` value.
4139 .. index:: -Wunused (gcc)
4142 The warnings controlled by the :switch:`-gnatw` switch are generated by
4143 the front end of the compiler. The GCC back end can provide
4144 additional warnings and they are controlled by the :switch:`-W` switch.
4145 For example, :switch:`-Wunused` activates back end
4146 warnings for entities that are declared but not referenced.
4149 .. index:: -Wuninitialized (gcc)
4151 :switch:`-Wuninitialized`
4152 Similarly, :switch:`-Wuninitialized` activates
4153 the back end warning for uninitialized variables. This switch must be
4154 used in conjunction with an optimization level greater than zero.
4157 .. index:: -Wstack-usage (gcc)
4159 :switch:`-Wstack-usage={len}`
4160 Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
4161 See :ref:`Static_Stack_Usage_Analysis` for details.
4164 .. index:: -Wall (gcc)
4167 This switch enables most warnings from the GCC back end.
4168 The code generator detects a number of warning situations that are missed
4169 by the GNAT front end, and this switch can be used to activate them.
4170 The use of this switch also sets the default front end warning mode to
4171 :switch:`-gnatwa`, that is, most front end warnings activated as well.
4177 Conversely, this switch suppresses warnings from the GCC back end.
4178 The use of this switch also sets the default front end warning mode to
4179 :switch:`-gnatws`, that is, front end warnings suppressed as well.
4182 .. index:: -Werror (gcc)
4185 This switch causes warnings from the GCC back end to be treated as
4186 errors. The warning string still appears, but the warning messages are
4187 counted as errors, and prevent the generation of an object file.
4190 A string of warning parameters can be used in the same parameter. For example::
4195 will turn on all optional warnings except for unrecognized pragma warnings,
4196 and also specify that warnings should be treated as errors.
4198 When no switch :switch:`-gnatw` is used, this is equivalent to:
4200 * :switch:`-gnatw.a`
4204 * :switch:`-gnatw.b`
4208 * :switch:`-gnatw.C`
4212 * :switch:`-gnatw.D`
4216 * :switch:`-gnatw.F`
4222 * :switch:`-gnatw.H`
4228 * :switch:`-gnatw.J`
4232 * :switch:`-gnatw.K`
4236 * :switch:`-gnatw.L`
4240 * :switch:`-gnatw.m`
4244 * :switch:`-gnatw.N`
4248 * :switch:`-gnatw.O`
4252 * :switch:`-gnatw.P`
4256 * :switch:`-gnatw.Q`
4260 * :switch:`-gnatw.R`
4262 * :switch:`-gnatw.S`
4266 * :switch:`-gnatw.t`
4270 * :switch:`-gnatw.U`
4274 * :switch:`-gnatw.v`
4278 * :switch:`-gnatw.W`
4282 * :switch:`-gnatw.X`
4286 * :switch:`-gnatw.Y`
4290 * :switch:`-gnatw.z`
4292 .. _Debugging_and_Assertion_Control:
4294 Debugging and Assertion Control
4295 -------------------------------
4299 .. index:: -gnata (gcc)
4304 .. index:: Assertions
4305 .. index:: Precondition
4306 .. index:: Postcondition
4307 .. index:: Type invariants
4308 .. index:: Subtype predicates
4310 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
4312 pragma Assertion_Policy (Check);
4314 Which is a shorthand for::
4316 pragma Assertion_Policy
4318 Static_Predicate => Check,
4319 Dynamic_Predicate => Check,
4323 Post'Class => Check,
4324 Type_Invariant => Check,
4325 Type_Invariant'Class => Check);
4327 The pragmas ``Assert`` and ``Debug`` normally have no effect and
4328 are ignored. This switch, where ``a`` stands for 'assert', causes
4329 pragmas ``Assert`` and ``Debug`` to be activated. This switch also
4330 causes preconditions, postconditions, subtype predicates, and
4331 type invariants to be activated.
4333 The pragmas have the form::
4335 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4336 pragma Debug (<procedure call>)
4337 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4338 pragma Predicate (<type-local-name>, <Boolean-expression>)
4339 pragma Precondition (<Boolean-expression>, <string-expression>)
4340 pragma Postcondition (<Boolean-expression>, <string-expression>)
4342 The aspects have the form::
4344 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4345 => <Boolean-expression>;
4347 The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
4348 If the result is ``True``, the pragma has no effect (other than
4349 possible side effects from evaluating the expression). If the result is
4350 ``False``, the exception ``Assert_Failure`` declared in the package
4351 ``System.Assertions`` is raised (passing ``static-string-expression``, if
4352 present, as the message associated with the exception). If no string
4353 expression is given, the default is a string containing the file name and
4354 line number of the pragma.
4356 The ``Debug`` pragma causes ``procedure`` to be called. Note that
4357 ``pragma Debug`` may appear within a declaration sequence, allowing
4358 debugging procedures to be called between declarations.
4360 For the aspect specification, the ``Boolean-expression`` is evaluated.
4361 If the result is ``True``, the aspect has no effect. If the result
4362 is ``False``, the exception ``Assert_Failure`` is raised.
4364 .. _Validity_Checking:
4369 .. index:: Validity Checking
4371 The Ada Reference Manual defines the concept of invalid values (see
4372 RM 13.9.1). The primary source of invalid values is uninitialized
4373 variables. A scalar variable that is left uninitialized may contain
4374 an invalid value; the concept of invalid does not apply to access or
4377 It is an error to read an invalid value, but the RM does not require
4378 run-time checks to detect such errors, except for some minimal
4379 checking to prevent erroneous execution (i.e. unpredictable
4380 behavior). This corresponds to the :switch:`-gnatVd` switch below,
4381 which is the default. For example, by default, if the expression of a
4382 case statement is invalid, it will raise Constraint_Error rather than
4383 causing a wild jump, and if an array index on the left-hand side of an
4384 assignment is invalid, it will raise Constraint_Error rather than
4385 overwriting an arbitrary memory location.
4387 The :switch:`-gnatVa` may be used to enable additional validity checks,
4388 which are not required by the RM. These checks are often very
4389 expensive (which is why the RM does not require them). These checks
4390 are useful in tracking down uninitialized variables, but they are
4391 not usually recommended for production builds, and in particular
4392 we do not recommend using these extra validity checking options in
4393 combination with optimization, since this can confuse the optimizer.
4394 If performance is a consideration, leading to the need to optimize,
4395 then the validity checking options should not be used.
4397 The other :switch:`-gnatV{x}` switches below allow finer-grained
4398 control; you can enable whichever validity checks you desire. However,
4399 for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
4400 default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
4401 sufficient for non-debugging use.
4403 The :switch:`-gnatB` switch tells the compiler to assume that all
4404 values are valid (that is, within their declared subtype range)
4405 except in the context of a use of the Valid attribute. This means
4406 the compiler can generate more efficient code, since the range
4407 of values is better known at compile time. However, an uninitialized
4408 variable can cause wild jumps and memory corruption in this mode.
4410 The :switch:`-gnatV{x}` switch allows control over the validity
4411 checking mode as described below.
4412 The ``x`` argument is a string of letters that
4413 indicate validity checks that are performed or not performed in addition
4414 to the default checks required by Ada as described above.
4417 .. index:: -gnatVa (gcc)
4420 *All validity checks.*
4422 All validity checks are turned on.
4423 That is, :switch:`-gnatVa` is
4424 equivalent to ``gnatVcdfimorst``.
4427 .. index:: -gnatVc (gcc)
4430 *Validity checks for copies.*
4432 The right hand side of assignments, and the initializing values of
4433 object declarations are validity checked.
4436 .. index:: -gnatVd (gcc)
4439 *Default (RM) validity checks.*
4441 Some validity checks are done by default following normal Ada semantics
4443 A check is done in case statements that the expression is within the range
4444 of the subtype. If it is not, Constraint_Error is raised.
4445 For assignments to array components, a check is done that the expression used
4446 as index is within the range. If it is not, Constraint_Error is raised.
4447 Both these validity checks may be turned off using switch :switch:`-gnatVD`.
4448 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
4449 switch :switch:`-gnatVd` will leave the checks turned on.
4450 Switch :switch:`-gnatVD` should be used only if you are sure that all such
4451 expressions have valid values. If you use this switch and invalid values
4452 are present, then the program is erroneous, and wild jumps or memory
4453 overwriting may occur.
4456 .. index:: -gnatVe (gcc)
4459 *Validity checks for elementary components.*
4461 In the absence of this switch, assignments to record or array components are
4462 not validity checked, even if validity checks for assignments generally
4463 (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not
4464 require valid data, but assignment of individual components does. So for
4465 example, there is a difference between copying the elements of an array with a
4466 slice assignment, compared to assigning element by element in a loop. This
4467 switch allows you to turn off validity checking for components, even when they
4468 are assigned component by component.
4471 .. index:: -gnatVf (gcc)
4474 *Validity checks for floating-point values.*
4476 In the absence of this switch, validity checking occurs only for discrete
4477 values. If :switch:`-gnatVf` is specified, then validity checking also applies
4478 for floating-point values, and NaNs and infinities are considered invalid,
4479 as well as out of range values for constrained types. Note that this means
4480 that standard IEEE infinity mode is not allowed. The exact contexts
4481 in which floating-point values are checked depends on the setting of other
4482 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
4483 (the order does not matter) specifies that floating-point parameters of mode
4484 ``in`` should be validity checked.
4487 .. index:: -gnatVi (gcc)
4490 *Validity checks for ``in`` mode parameters.*
4492 Arguments for parameters of mode ``in`` are validity checked in function
4493 and procedure calls at the point of call.
4496 .. index:: -gnatVm (gcc)
4499 *Validity checks for ``in out`` mode parameters.*
4501 Arguments for parameters of mode ``in out`` are validity checked in
4502 procedure calls at the point of call. The ``'m'`` here stands for
4503 modify, since this concerns parameters that can be modified by the call.
4504 Note that there is no specific option to test ``out`` parameters,
4505 but any reference within the subprogram will be tested in the usual
4506 manner, and if an invalid value is copied back, any reference to it
4507 will be subject to validity checking.
4510 .. index:: -gnatVn (gcc)
4513 *No validity checks.*
4515 This switch turns off all validity checking, including the default checking
4516 for case statements and left hand side subscripts. Note that the use of
4517 the switch :switch:`-gnatp` suppresses all run-time checks, including
4518 validity checks, and thus implies :switch:`-gnatVn`. When this switch
4519 is used, it cancels any other :switch:`-gnatV` previously issued.
4522 .. index:: -gnatVo (gcc)
4525 *Validity checks for operator and attribute operands.*
4527 Arguments for predefined operators and attributes are validity checked.
4528 This includes all operators in package ``Standard``,
4529 the shift operators defined as intrinsic in package ``Interfaces``
4530 and operands for attributes such as ``Pos``. Checks are also made
4531 on individual component values for composite comparisons, and on the
4532 expressions in type conversions and qualified expressions. Checks are
4533 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4536 .. index:: -gnatVp (gcc)
4539 *Validity checks for parameters.*
4541 This controls the treatment of parameters within a subprogram (as opposed
4542 to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing
4543 of parameters on a call. If either of these call options is used, then
4544 normally an assumption is made within a subprogram that the input arguments
4545 have been validity checking at the point of call, and do not need checking
4546 again within a subprogram). If :switch:`-gnatVp` is set, then this assumption
4547 is not made, and parameters are not assumed to be valid, so their validity
4548 will be checked (or rechecked) within the subprogram.
4551 .. index:: -gnatVr (gcc)
4554 *Validity checks for function returns.*
4556 The expression in ``return`` statements in functions is validity
4560 .. index:: -gnatVs (gcc)
4563 *Validity checks for subscripts.*
4565 All subscripts expressions are checked for validity, whether they appear
4566 on the right side or left side (in default mode only left side subscripts
4567 are validity checked).
4570 .. index:: -gnatVt (gcc)
4573 *Validity checks for tests.*
4575 Expressions used as conditions in ``if``, ``while`` or ``exit``
4576 statements are checked, as well as guard expressions in entry calls.
4579 The :switch:`-gnatV` switch may be followed by a string of letters
4580 to turn on a series of validity checking options.
4581 For example, :switch:`-gnatVcr`
4582 specifies that in addition to the default validity checking, copies and
4583 function return expressions are to be validity checked.
4584 In order to make it easier to specify the desired combination of effects,
4585 the upper case letters ``CDFIMORST`` may
4586 be used to turn off the corresponding lower case option.
4587 Thus :switch:`-gnatVaM` turns on all validity checking options except for
4588 checking of ``in out`` parameters.
4590 The specification of additional validity checking generates extra code (and
4591 in the case of :switch:`-gnatVa` the code expansion can be substantial).
4592 However, these additional checks can be very useful in detecting
4593 uninitialized variables, incorrect use of unchecked conversion, and other
4594 errors leading to invalid values. The use of pragma ``Initialize_Scalars``
4595 is useful in conjunction with the extra validity checking, since this
4596 ensures that wherever possible uninitialized variables have invalid values.
4598 See also the pragma ``Validity_Checks`` which allows modification of
4599 the validity checking mode at the program source level, and also allows for
4600 temporary disabling of validity checks.
4607 .. index:: Style checking
4609 .. index:: -gnaty (gcc)
4611 The :switch:`-gnatyx` switch causes the compiler to
4612 enforce specified style rules. A limited set of style rules has been used
4613 in writing the GNAT sources themselves. This switch allows user programs
4614 to activate all or some of these checks. If the source program fails a
4615 specified style check, an appropriate message is given, preceded by
4616 the character sequence '(style)'. This message does not prevent
4617 successful compilation (unless the :switch:`-gnatwe` switch is used).
4619 Note that this is by no means intended to be a general facility for
4620 checking arbitrary coding standards. It is simply an embedding of the
4621 style rules we have chosen for the GNAT sources. If you are starting
4622 a project which does not have established style standards, you may
4623 find it useful to adopt the entire set of GNAT coding standards, or
4624 some subset of them.
4626 .. only:: PRO or GPL
4628 If you already have an established set of coding
4629 standards, then the selected style checking options may
4630 indeed correspond to choices you have made, but for general checking
4631 of an existing set of coding rules, you should look to the gnatcheck
4632 tool, which is designed for that purpose.
4634 The string ``x`` is a sequence of letters or digits
4635 indicating the particular style
4636 checks to be performed. The following checks are defined:
4639 .. index:: -gnaty[0-9] (gcc)
4642 *Specify indentation level.*
4644 If a digit from 1-9 appears
4645 in the string after :switch:`-gnaty`
4646 then proper indentation is checked, with the digit indicating the
4647 indentation level required. A value of zero turns off this style check.
4648 The general style of required indentation is as specified by
4649 the examples in the Ada Reference Manual. Full line comments must be
4650 aligned with the ``--`` starting on a column that is a multiple of
4651 the alignment level, or they may be aligned the same way as the following
4652 non-blank line (this is useful when full line comments appear in the middle
4653 of a statement, or they may be aligned with the source line on the previous
4656 .. index:: -gnatya (gcc)
4659 *Check attribute casing.*
4661 Attribute names, including the case of keywords such as ``digits``
4662 used as attributes names, must be written in mixed case, that is, the
4663 initial letter and any letter following an underscore must be uppercase.
4664 All other letters must be lowercase.
4667 .. index:: -gnatyA (gcc)
4670 *Use of array index numbers in array attributes.*
4672 When using the array attributes First, Last, Range,
4673 or Length, the index number must be omitted for one-dimensional arrays
4674 and is required for multi-dimensional arrays.
4677 .. index:: -gnatyb (gcc)
4680 *Blanks not allowed at statement end.*
4682 Trailing blanks are not allowed at the end of statements. The purpose of this
4683 rule, together with h (no horizontal tabs), is to enforce a canonical format
4684 for the use of blanks to separate source tokens.
4687 .. index:: -gnatyB (gcc)
4690 *Check Boolean operators.*
4692 The use of AND/OR operators is not permitted except in the cases of modular
4693 operands, array operands, and simple stand-alone boolean variables or
4694 boolean constants. In all other cases ``and then``/`or else` are
4698 .. index:: -gnatyc (gcc)
4701 *Check comments, double space.*
4703 Comments must meet the following set of rules:
4705 * The ``--`` that starts the column must either start in column one,
4706 or else at least one blank must precede this sequence.
4708 * Comments that follow other tokens on a line must have at least one blank
4709 following the ``--`` at the start of the comment.
4711 * Full line comments must have at least two blanks following the
4712 ``--`` that starts the comment, with the following exceptions.
4714 * A line consisting only of the ``--`` characters, possibly preceded
4715 by blanks is permitted.
4717 * A comment starting with ``--x`` where ``x`` is a special character
4719 This allows proper processing of the output from specialized tools
4720 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
4722 language (where ``--#`` is used). For the purposes of this rule, a
4723 special character is defined as being in one of the ASCII ranges
4724 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
4725 Note that this usage is not permitted
4726 in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
4728 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4729 permitted. This allows the construction of box comments where lines of minus
4730 signs are used to form the top and bottom of the box.
4732 * A comment that starts and ends with ``--`` is permitted as long as at
4733 least one blank follows the initial ``--``. Together with the preceding
4734 rule, this allows the construction of box comments, as shown in the following
4739 ---------------------------
4740 -- This is a box comment --
4741 -- with two text lines. --
4742 ---------------------------
4745 .. index:: -gnatyC (gcc)
4748 *Check comments, single space.*
4750 This is identical to ``c`` except that only one space
4751 is required following the ``--`` of a comment instead of two.
4754 .. index:: -gnatyd (gcc)
4757 *Check no DOS line terminators present.*
4759 All lines must be terminated by a single ASCII.LF
4760 character (in particular the DOS line terminator sequence CR/LF is not
4764 .. index:: -gnatyD (gcc)
4767 *Check declared identifiers in mixed case.*
4769 Declared identifiers must be in mixed case, as in
4770 This_Is_An_Identifier. Use -gnatyr in addition to ensure
4771 that references match declarations.
4774 .. index:: -gnatye (gcc)
4777 *Check end/exit labels.*
4779 Optional labels on ``end`` statements ending subprograms and on
4780 ``exit`` statements exiting named loops, are required to be present.
4783 .. index:: -gnatyf (gcc)
4786 *No form feeds or vertical tabs.*
4788 Neither form feeds nor vertical tab characters are permitted
4792 .. index:: -gnatyg (gcc)
4797 The set of style check switches is set to match that used by the GNAT sources.
4798 This may be useful when developing code that is eventually intended to be
4799 incorporated into GNAT. Currently this is equivalent to :switch:`-gnatyydISux`)
4800 but additional style switches may be added to this set in the future without
4804 .. index:: -gnatyh (gcc)
4807 *No horizontal tabs.*
4809 Horizontal tab characters are not permitted in the source text.
4810 Together with the b (no blanks at end of line) check, this
4811 enforces a canonical form for the use of blanks to separate
4815 .. index:: -gnatyi (gcc)
4818 *Check if-then layout.*
4820 The keyword ``then`` must appear either on the same
4821 line as corresponding ``if``, or on a line on its own, lined
4822 up under the ``if``.
4825 .. index:: -gnatyI (gcc)
4828 *check mode IN keywords.*
4830 Mode ``in`` (the default mode) is not
4831 allowed to be given explicitly. ``in out`` is fine,
4832 but not ``in`` on its own.
4835 .. index:: -gnatyk (gcc)
4838 *Check keyword casing.*
4840 All keywords must be in lower case (with the exception of keywords
4841 such as ``digits`` used as attribute names to which this check
4845 .. index:: -gnatyl (gcc)
4850 Layout of statement and declaration constructs must follow the
4851 recommendations in the Ada Reference Manual, as indicated by the
4852 form of the syntax rules. For example an ``else`` keyword must
4853 be lined up with the corresponding ``if`` keyword.
4855 There are two respects in which the style rule enforced by this check
4856 option are more liberal than those in the Ada Reference Manual. First
4857 in the case of record declarations, it is permissible to put the
4858 ``record`` keyword on the same line as the ``type`` keyword, and
4859 then the ``end`` in ``end record`` must line up under ``type``.
4860 This is also permitted when the type declaration is split on two lines.
4861 For example, any of the following three layouts is acceptable:
4882 Second, in the case of a block statement, a permitted alternative
4883 is to put the block label on the same line as the ``declare`` or
4884 ``begin`` keyword, and then line the ``end`` keyword up under
4885 the block label. For example both the following are permitted:
4902 The same alternative format is allowed for loops. For example, both of
4903 the following are permitted:
4907 Clear : while J < 10 loop
4917 .. index:: -gnatyLnnn (gcc)
4920 *Set maximum nesting level.*
4922 The maximum level of nesting of constructs (including subprograms, loops,
4923 blocks, packages, and conditionals) may not exceed the given value
4924 *nnn*. A value of zero disconnects this style check.
4927 .. index:: -gnatym (gcc)
4930 *Check maximum line length.*
4932 The length of source lines must not exceed 79 characters, including
4933 any trailing blanks. The value of 79 allows convenient display on an
4934 80 character wide device or window, allowing for possible special
4935 treatment of 80 character lines. Note that this count is of
4936 characters in the source text. This means that a tab character counts
4937 as one character in this count and a wide character sequence counts as
4938 a single character (however many bytes are needed in the encoding).
4941 .. index:: -gnatyMnnn (gcc)
4944 *Set maximum line length.*
4946 The length of lines must not exceed the
4947 given value *nnn*. The maximum value that can be specified is 32767.
4948 If neither style option for setting the line length is used, then the
4949 default is 255. This also controls the maximum length of lexical elements,
4950 where the only restriction is that they must fit on a single line.
4953 .. index:: -gnatyn (gcc)
4956 *Check casing of entities in Standard.*
4958 Any identifier from Standard must be cased
4959 to match the presentation in the Ada Reference Manual (for example,
4960 ``Integer`` and ``ASCII.NUL``).
4963 .. index:: -gnatyN (gcc)
4966 *Turn off all style checks.*
4968 All style check options are turned off.
4971 .. index:: -gnatyo (gcc)
4974 *Check order of subprogram bodies.*
4976 All subprogram bodies in a given scope
4977 (e.g., a package body) must be in alphabetical order. The ordering
4978 rule uses normal Ada rules for comparing strings, ignoring casing
4979 of letters, except that if there is a trailing numeric suffix, then
4980 the value of this suffix is used in the ordering (e.g., Junk2 comes
4984 .. index:: -gnatyO (gcc)
4987 *Check that overriding subprograms are explicitly marked as such.*
4989 This applies to all subprograms of a derived type that override a primitive
4990 operation of the type, for both tagged and untagged types. In particular,
4991 the declaration of a primitive operation of a type extension that overrides
4992 an inherited operation must carry an overriding indicator. Another case is
4993 the declaration of a function that overrides a predefined operator (such
4994 as an equality operator).
4997 .. index:: -gnatyp (gcc)
5000 *Check pragma casing.*
5002 Pragma names must be written in mixed case, that is, the
5003 initial letter and any letter following an underscore must be uppercase.
5004 All other letters must be lowercase. An exception is that SPARK_Mode is
5005 allowed as an alternative for Spark_Mode.
5008 .. index:: -gnatyr (gcc)
5013 All identifier references must be cased in the same way as the
5014 corresponding declaration. No specific casing style is imposed on
5015 identifiers. The only requirement is for consistency of references
5019 .. index:: -gnatys (gcc)
5022 *Check separate specs.*
5024 Separate declarations ('specs') are required for subprograms (a
5025 body is not allowed to serve as its own declaration). The only
5026 exception is that parameterless library level procedures are
5027 not required to have a separate declaration. This exception covers
5028 the most frequent form of main program procedures.
5031 .. index:: -gnatyS (gcc)
5034 *Check no statements after then/else.*
5036 No statements are allowed
5037 on the same line as a ``then`` or ``else`` keyword following the
5038 keyword in an ``if`` statement. ``or else`` and ``and then`` are not
5039 affected, and a special exception allows a pragma to appear after ``else``.
5042 .. index:: -gnatyt (gcc)
5045 *Check token spacing.*
5047 The following token spacing rules are enforced:
5049 * The keywords ``abs`` and ``not`` must be followed by a space.
5051 * The token ``=>`` must be surrounded by spaces.
5053 * The token ``<>`` must be preceded by a space or a left parenthesis.
5055 * Binary operators other than ``**`` must be surrounded by spaces.
5056 There is no restriction on the layout of the ``**`` binary operator.
5058 * Colon must be surrounded by spaces.
5060 * Colon-equal (assignment, initialization) must be surrounded by spaces.
5062 * Comma must be the first non-blank character on the line, or be
5063 immediately preceded by a non-blank character, and must be followed
5066 * If the token preceding a left parenthesis ends with a letter or digit, then
5067 a space must separate the two tokens.
5069 * If the token following a right parenthesis starts with a letter or digit, then
5070 a space must separate the two tokens.
5072 * A right parenthesis must either be the first non-blank character on
5073 a line, or it must be preceded by a non-blank character.
5075 * A semicolon must not be preceded by a space, and must not be followed by
5076 a non-blank character.
5078 * A unary plus or minus may not be followed by a space.
5080 * A vertical bar must be surrounded by spaces.
5082 Exactly one blank (and no other white space) must appear between
5083 a ``not`` token and a following ``in`` token.
5086 .. index:: -gnatyu (gcc)
5089 *Check unnecessary blank lines.*
5091 Unnecessary blank lines are not allowed. A blank line is considered
5092 unnecessary if it appears at the end of the file, or if more than
5093 one blank line occurs in sequence.
5096 .. index:: -gnatyx (gcc)
5099 *Check extra parentheses.*
5101 Unnecessary extra level of parentheses (C-style) are not allowed
5102 around conditions in ``if`` statements, ``while`` statements and
5103 ``exit`` statements.
5106 .. index:: -gnatyy (gcc)
5109 *Set all standard style check options.*
5111 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
5112 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
5113 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
5114 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
5117 .. index:: -gnaty- (gcc)
5120 *Remove style check options.*
5122 This causes any subsequent options in the string to act as canceling the
5123 corresponding style check option. To cancel maximum nesting level control,
5124 use the ``L`` parameter without any integer value after that, because any
5125 digit following *-* in the parameter string of the :switch:`-gnaty`
5126 option will be treated as canceling the indentation check. The same is true
5127 for the ``M`` parameter. ``y`` and ``N`` parameters are not
5131 .. index:: -gnaty+ (gcc)
5134 *Enable style check options.*
5136 This causes any subsequent options in the string to enable the corresponding
5137 style check option. That is, it cancels the effect of a previous -,
5141 .. end of switch description (leave this comment to ease automatic parsing for
5144 In the above rules, appearing in column one is always permitted, that is,
5145 counts as meeting either a requirement for a required preceding space,
5146 or as meeting a requirement for no preceding space.
5148 Appearing at the end of a line is also always permitted, that is, counts
5149 as meeting either a requirement for a following space, or as meeting
5150 a requirement for no following space.
5152 If any of these style rules is violated, a message is generated giving
5153 details on the violation. The initial characters of such messages are
5154 always '`(style)`'. Note that these messages are treated as warning
5155 messages, so they normally do not prevent the generation of an object
5156 file. The :switch:`-gnatwe` switch can be used to treat warning messages,
5157 including style messages, as fatal errors.
5159 The switch :switch:`-gnaty` on its own (that is not
5160 followed by any letters or digits) is equivalent
5161 to the use of :switch:`-gnatyy` as described above, that is all
5162 built-in standard style check options are enabled.
5164 The switch :switch:`-gnatyN` clears any previously set style checks.
5166 .. _Run-Time_Checks:
5171 .. index:: Division by zero
5173 .. index:: Access before elaboration
5175 .. index:: Checks, division by zero
5177 .. index:: Checks, access before elaboration
5179 .. index:: Checks, stack overflow checking
5181 By default, the following checks are suppressed: stack overflow
5182 checks, and checks for access before elaboration on subprogram
5183 calls. All other checks, including overflow checks, range checks and
5184 array bounds checks, are turned on by default. The following ``gcc``
5185 switches refine this default behavior.
5187 .. index:: -gnatp (gcc)
5190 .. index:: Suppressing checks
5192 .. index:: Checks, suppressing
5194 This switch causes the unit to be compiled
5195 as though ``pragma Suppress (All_checks)``
5196 had been present in the source. Validity checks are also eliminated (in
5197 other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
5198 Use this switch to improve the performance
5199 of the code at the expense of safety in the presence of invalid data or
5202 Note that when checks are suppressed, the compiler is allowed, but not
5203 required, to omit the checking code. If the run-time cost of the
5204 checking code is zero or near-zero, the compiler will generate it even
5205 if checks are suppressed. In particular, if the compiler can prove
5206 that a certain check will necessarily fail, it will generate code to
5207 do an unconditional 'raise', even if checks are suppressed. The
5208 compiler warns in this case. Another case in which checks may not be
5209 eliminated is when they are embedded in certain run-time routines such
5210 as math library routines.
5212 Of course, run-time checks are omitted whenever the compiler can prove
5213 that they will not fail, whether or not checks are suppressed.
5215 Note that if you suppress a check that would have failed, program
5216 execution is erroneous, which means the behavior is totally
5217 unpredictable. The program might crash, or print wrong answers, or
5218 do anything else. It might even do exactly what you wanted it to do
5219 (and then it might start failing mysteriously next week or next
5220 year). The compiler will generate code based on the assumption that
5221 the condition being checked is true, which can result in erroneous
5222 execution if that assumption is wrong.
5224 The checks subject to suppression include all the checks defined by the Ada
5225 standard, the additional implementation defined checks ``Alignment_Check``,
5226 ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``,
5227 and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``.
5228 Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option.
5230 If the code depends on certain checks being active, you can use
5231 pragma ``Unsuppress`` either as a configuration pragma or as
5232 a local pragma to make sure that a specified check is performed
5233 even if ``gnatp`` is specified.
5235 The :switch:`-gnatp` switch has no effect if a subsequent
5236 :switch:`-gnat-p` switch appears.
5239 .. index:: -gnat-p (gcc)
5240 .. index:: Suppressing checks
5241 .. index:: Checks, suppressing
5245 This switch cancels the effect of a previous ``gnatp`` switch.
5248 .. index:: -gnato?? (gcc)
5249 .. index:: Overflow checks
5250 .. index:: Overflow mode
5251 .. index:: Check, overflow
5254 This switch controls the mode used for computing intermediate
5255 arithmetic integer operations, and also enables overflow checking.
5256 For a full description of overflow mode and checking control, see
5257 the 'Overflow Check Handling in GNAT' appendix in this
5260 Overflow checks are always enabled by this switch. The argument
5261 controls the mode, using the codes
5265 In STRICT mode, intermediate operations are always done using the
5266 base type, and overflow checking ensures that the result is within
5267 the base type range.
5271 In MINIMIZED mode, overflows in intermediate operations are avoided
5272 where possible by using a larger integer type for the computation
5273 (typically ``Long_Long_Integer``). Overflow checking ensures that
5274 the result fits in this larger integer type.
5278 In ELIMINATED mode, overflows in intermediate operations are avoided
5279 by using multi-precision arithmetic. In this case, overflow checking
5280 has no effect on intermediate operations (since overflow is impossible).
5282 If two digits are present after :switch:`-gnato` then the first digit
5283 sets the mode for expressions outside assertions, and the second digit
5284 sets the mode for expressions within assertions. Here assertions is used
5285 in the technical sense (which includes for example precondition and
5286 postcondition expressions).
5288 If one digit is present, the corresponding mode is applicable to both
5289 expressions within and outside assertion expressions.
5291 If no digits are present, the default is to enable overflow checks
5292 and set STRICT mode for both kinds of expressions. This is compatible
5293 with the use of :switch:`-gnato` in previous versions of GNAT.
5295 .. index:: Machine_Overflows
5297 Note that the :switch:`-gnato??` switch does not affect the code generated
5298 for any floating-point operations; it applies only to integer semantics.
5299 For floating-point, GNAT has the ``Machine_Overflows``
5300 attribute set to ``False`` and the normal mode of operation is to
5301 generate IEEE NaN and infinite values on overflow or invalid operations
5302 (such as dividing 0.0 by 0.0).
5304 The reason that we distinguish overflow checking from other kinds of
5305 range constraint checking is that a failure of an overflow check, unlike
5306 for example the failure of a range check, can result in an incorrect
5307 value, but cannot cause random memory destruction (like an out of range
5308 subscript), or a wild jump (from an out of range case value). Overflow
5309 checking is also quite expensive in time and space, since in general it
5310 requires the use of double length arithmetic.
5312 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
5313 so overflow checking is performed in STRICT mode by default.
5316 .. index:: -gnatE (gcc)
5317 .. index:: Elaboration checks
5318 .. index:: Check, elaboration
5321 Enables dynamic checks for access-before-elaboration
5322 on subprogram calls and generic instantiations.
5323 Note that :switch:`-gnatE` is not necessary for safety, because in the
5324 default mode, GNAT ensures statically that the checks would not fail.
5325 For full details of the effect and use of this switch,
5326 :ref:`Compiling_with_gcc`.
5329 .. index:: -fstack-check (gcc)
5330 .. index:: Stack Overflow Checking
5331 .. index:: Checks, stack overflow checking
5333 :switch:`-fstack-check`
5334 Activates stack overflow checking. For full details of the effect and use of
5335 this switch see :ref:`Stack_Overflow_Checking`.
5337 .. index:: Unsuppress
5339 The setting of these switches only controls the default setting of the
5340 checks. You may modify them using either ``Suppress`` (to remove
5341 checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
5345 .. _Using_gcc_for_Syntax_Checking:
5347 Using ``gcc`` for Syntax Checking
5348 ---------------------------------
5350 .. index:: -gnats (gcc)
5353 The ``s`` stands for 'syntax'.
5355 Run GNAT in syntax checking only mode. For
5356 example, the command
5360 $ gcc -c -gnats x.adb
5362 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5363 series of files in a single command
5364 , and can use wildcards to specify such a group of files.
5365 Note that you must specify the :switch:`-c` (compile
5366 only) flag in addition to the :switch:`-gnats` flag.
5368 You may use other switches in conjunction with :switch:`-gnats`. In
5369 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
5370 format of any generated error messages.
5372 When the source file is empty or contains only empty lines and/or comments,
5373 the output is a warning:
5378 $ gcc -c -gnats -x ada toto.txt
5379 toto.txt:1:01: warning: empty file, contains no compilation units
5383 Otherwise, the output is simply the error messages, if any. No object file or
5384 ALI file is generated by a syntax-only compilation. Also, no units other
5385 than the one specified are accessed. For example, if a unit ``X``
5386 |withs| a unit ``Y``, compiling unit ``X`` in syntax
5387 check only mode does not access the source file containing unit
5390 .. index:: Multiple units, syntax checking
5392 Normally, GNAT allows only a single unit in a source file. However, this
5393 restriction does not apply in syntax-check-only mode, and it is possible
5394 to check a file containing multiple compilation units concatenated
5395 together. This is primarily used by the ``gnatchop`` utility
5396 (:ref:`Renaming_Files_with_gnatchop`).
5398 .. _Using_gcc_for_Semantic_Checking:
5400 Using ``gcc`` for Semantic Checking
5401 -----------------------------------
5405 .. index:: -gnatc (gcc)
5408 The ``c`` stands for 'check'.
5409 Causes the compiler to operate in semantic check mode,
5410 with full checking for all illegalities specified in the
5411 Ada Reference Manual, but without generation of any object code
5412 (no object file is generated).
5414 Because dependent files must be accessed, you must follow the GNAT
5415 semantic restrictions on file structuring to operate in this mode:
5417 * The needed source files must be accessible
5418 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5420 * Each file must contain only one compilation unit.
5422 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5424 The output consists of error messages as appropriate. No object file is
5425 generated. An :file:`ALI` file is generated for use in the context of
5426 cross-reference tools, but this file is marked as not being suitable
5427 for binding (since no object file is generated).
5428 The checking corresponds exactly to the notion of
5429 legality in the Ada Reference Manual.
5431 Any unit can be compiled in semantics-checking-only mode, including
5432 units that would not normally be compiled (subunits,
5433 and specifications where a separate body is present).
5435 .. _Compiling_Different_Versions_of_Ada:
5437 Compiling Different Versions of Ada
5438 -----------------------------------
5440 The switches described in this section allow you to explicitly specify
5441 the version of the Ada language that your programs are written in.
5442 The default mode is Ada 2012,
5443 but you can also specify Ada 95, Ada 2005 mode, or
5444 indicate Ada 83 compatibility mode.
5447 .. index:: Compatibility with Ada 83
5448 .. index:: -gnat83 (gcc)
5449 .. index:: ACVC, Ada 83 tests
5450 .. index:: Ada 83 mode
5452 :switch:`-gnat83` (Ada 83 Compatibility Mode)
5453 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5454 specifies that the program is to be compiled in Ada 83 mode. With
5455 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5456 semantics where this can be done easily.
5457 It is not possible to guarantee this switch does a perfect
5458 job; some subtle tests, such as are
5459 found in earlier ACVC tests (and that have been removed from the ACATS suite
5460 for Ada 95), might not compile correctly.
5461 Nevertheless, this switch may be useful in some circumstances, for example
5462 where, due to contractual reasons, existing code needs to be maintained
5463 using only Ada 83 features.
5465 With few exceptions (most notably the need to use ``<>`` on
5466 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5467 the use of the new Ada 95 / Ada 2005
5468 reserved words, and the use of packages
5469 with optional bodies), it is not necessary to specify the
5470 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
5471 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5472 a correct Ada 83 program is usually also a correct program
5473 in these later versions of the language standard. For further information
5474 please refer to the *Compatibility and Porting Guide* chapter in the
5475 :title:`GNAT Reference Manual`.
5478 .. index:: -gnat95 (gcc)
5479 .. index:: Ada 95 mode
5481 :switch:`-gnat95` (Ada 95 mode)
5482 This switch directs the compiler to implement the Ada 95 version of the
5484 Since Ada 95 is almost completely upwards
5485 compatible with Ada 83, Ada 83 programs may generally be compiled using
5486 this switch (see the description of the :switch:`-gnat83` switch for further
5487 information about Ada 83 mode).
5488 If an Ada 2005 program is compiled in Ada 95 mode,
5489 uses of the new Ada 2005 features will cause error
5490 messages or warnings.
5492 This switch also can be used to cancel the effect of a previous
5493 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
5494 switch earlier in the command line.
5497 .. index:: -gnat05 (gcc)
5498 .. index:: -gnat2005 (gcc)
5499 .. index:: Ada 2005 mode
5501 :switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
5502 This switch directs the compiler to implement the Ada 2005 version of the
5503 language, as documented in the official Ada standards document.
5504 Since Ada 2005 is almost completely upwards
5505 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5506 may generally be compiled using this switch (see the description of the
5507 :switch:`-gnat83` and :switch:`-gnat95` switches for further
5511 .. index:: -gnat12 (gcc)
5512 .. index:: -gnat2012 (gcc)
5513 .. index:: Ada 2012 mode
5515 :switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
5516 This switch directs the compiler to implement the Ada 2012 version of the
5517 language (also the default).
5518 Since Ada 2012 is almost completely upwards
5519 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5520 Ada 83 and Ada 95 programs
5521 may generally be compiled using this switch (see the description of the
5522 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
5523 for further information).
5526 .. index:: -gnatX (gcc)
5527 .. index:: Ada language extensions
5528 .. index:: GNAT extensions
5530 :switch:`-gnatX` (Enable GNAT Extensions)
5531 This switch directs the compiler to implement the latest version of the
5532 language (currently Ada 2012) and also to enable certain GNAT implementation
5533 extensions that are not part of any Ada standard. For a full list of these
5534 extensions, see the GNAT reference manual.
5537 .. _Character_Set_Control:
5539 Character Set Control
5540 ---------------------
5542 .. index:: -gnati (gcc)
5545 Normally GNAT recognizes the Latin-1 character set in source program
5546 identifiers, as described in the Ada Reference Manual.
5548 GNAT to recognize alternate character sets in identifiers. ``c`` is a
5549 single character indicating the character set, as follows:
5551 ========== ======================================================
5552 *1* ISO 8859-1 (Latin-1) identifiers
5553 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5554 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5555 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5556 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5557 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5558 *p* IBM PC letters (code page 437) allowed in identifiers
5559 *8* IBM PC letters (code page 850) allowed in identifiers
5560 *f* Full upper-half codes allowed in identifiers
5561 *n* No upper-half codes allowed in identifiers
5562 *w* Wide-character codes (that is, codes greater than 255)
5563 allowed in identifiers
5564 ========== ======================================================
5566 See :ref:`Foreign_Language_Representation` for full details on the
5567 implementation of these character sets.
5570 .. index:: -gnatW (gcc)
5573 Specify the method of encoding for wide characters.
5574 ``e`` is one of the following:
5576 ========== ======================================================
5577 *h* Hex encoding (brackets coding also recognized)
5578 *u* Upper half encoding (brackets encoding also recognized)
5579 *s* Shift/JIS encoding (brackets encoding also recognized)
5580 *e* EUC encoding (brackets encoding also recognized)
5581 *8* UTF-8 encoding (brackets encoding also recognized)
5582 *b* Brackets encoding only (default value)
5583 ========== ======================================================
5585 For full details on these encoding
5586 methods see :ref:`Wide_Character_Encodings`.
5587 Note that brackets coding is always accepted, even if one of the other
5588 options is specified, so for example :switch:`-gnatW8` specifies that both
5589 brackets and UTF-8 encodings will be recognized. The units that are
5590 with'ed directly or indirectly will be scanned using the specified
5591 representation scheme, and so if one of the non-brackets scheme is
5592 used, it must be used consistently throughout the program. However,
5593 since brackets encoding is always recognized, it may be conveniently
5594 used in standard libraries, allowing these libraries to be used with
5595 any of the available coding schemes.
5597 Note that brackets encoding only applies to program text. Within comments,
5598 brackets are considered to be normal graphic characters, and bracket sequences
5599 are never recognized as wide characters.
5601 If no :switch:`-gnatW?` parameter is present, then the default
5602 representation is normally Brackets encoding only. However, if the
5603 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5604 byte order mark or BOM for UTF-8), then these three characters are
5605 skipped and the default representation for the file is set to UTF-8.
5607 Note that the wide character representation that is specified (explicitly
5608 or by default) for the main program also acts as the default encoding used
5609 for Wide_Text_IO files if not specifically overridden by a WCEM form
5613 When no :switch:`-gnatW?` is specified, then characters (other than wide
5614 characters represented using brackets notation) are treated as 8-bit
5615 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5616 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5617 characters in the range 16#00#..16#1F# are not accepted in program text
5618 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5619 in program text, but allowed and ignored in comments. Note in particular
5620 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5621 as an end of line in this default mode. If your source program contains
5622 instances of the NEL character used as a line terminator,
5623 you must use UTF-8 encoding for the whole
5624 source program. In default mode, all lines must be ended by a standard
5625 end of line sequence (CR, CR/LF, or LF).
5627 Note that the convention of simply accepting all upper half characters in
5628 comments means that programs that use standard ASCII for program text, but
5629 UTF-8 encoding for comments are accepted in default mode, providing that the
5630 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5631 This is a common mode for many programs with foreign language comments.
5633 .. _File_Naming_Control:
5638 .. index:: -gnatk (gcc)
5641 Activates file name 'krunching'. ``n``, a decimal integer in the range
5642 1-999, indicates the maximum allowable length of a file name (not
5643 including the :file:`.ads` or :file:`.adb` extension). The default is not
5644 to enable file name krunching.
5646 For the source file naming rules, :ref:`File_Naming_Rules`.
5648 .. _Subprogram_Inlining_Control:
5650 Subprogram Inlining Control
5651 ---------------------------
5653 .. index:: -gnatn (gcc)
5655 :switch:`-gnatn[12]`
5656 The ``n`` here is intended to suggest the first syllable of the word 'inline'.
5657 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
5658 actually occur, optimization must be enabled and, by default, inlining of
5659 subprograms across units is not performed. If you want to additionally
5660 enable inlining of subprograms specified by pragma ``Inline`` across units,
5661 you must also specify this switch.
5663 In the absence of this switch, GNAT does not attempt inlining across units
5664 and does not access the bodies of subprograms for which ``pragma Inline`` is
5665 specified if they are not in the current unit.
5667 You can optionally specify the inlining level: 1 for moderate inlining across
5668 units, which is a good compromise between compilation times and performances
5669 at run time, or 2 for full inlining across units, which may bring about
5670 longer compilation times. If no inlining level is specified, the compiler will
5671 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
5672 :switch:`-Os` and 2 for :switch:`-O3`.
5674 If you specify this switch the compiler will access these bodies,
5675 creating an extra source dependency for the resulting object file, and
5676 where possible, the call will be inlined.
5677 For further details on when inlining is possible
5678 see :ref:`Inlining_of_Subprograms`.
5681 .. index:: -gnatN (gcc)
5684 This switch activates front-end inlining which also
5685 generates additional dependencies.
5687 When using a gcc-based back end (in practice this means using any version
5688 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
5689 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
5690 Historically front end inlining was more extensive than the gcc back end
5691 inlining, but that is no longer the case.
5693 .. _Auxiliary_Output_Control:
5695 Auxiliary Output Control
5696 ------------------------
5698 .. index:: -gnatt (gcc)
5699 .. index:: Writing internal trees
5700 .. index:: Internal trees, writing to file
5703 Causes GNAT to write the internal tree for a unit to a file (with the
5704 extension :file:`.adt`.
5705 This not normally required, but is used by separate analysis tools.
5707 these tools do the necessary compilations automatically, so you should
5708 not have to specify this switch in normal operation.
5709 Note that the combination of switches :switch:`-gnatct`
5710 generates a tree in the form required by ASIS applications.
5713 .. index:: -gnatu (gcc)
5716 Print a list of units required by this compilation on :file:`stdout`.
5717 The listing includes all units on which the unit being compiled depends
5718 either directly or indirectly.
5721 .. index:: -pass-exit-codes (gcc)
5723 :switch:`-pass-exit-codes`
5724 If this switch is not used, the exit code returned by ``gcc`` when
5725 compiling multiple files indicates whether all source files have
5726 been successfully used to generate object files or not.
5728 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
5729 exit status and allows an integrated development environment to better
5730 react to a compilation failure. Those exit status are:
5732 ========== ======================================================
5733 *5* There was an error in at least one source file.
5734 *3* At least one source file did not generate an object file.
5735 *2* The compiler died unexpectedly (internal error for example).
5736 *0* An object file has been generated for every source file.
5737 ========== ======================================================
5739 .. _Debugging_Control:
5744 .. index:: Debugging options
5747 .. index:: -gnatd (gcc)
5750 Activate internal debugging switches. ``x`` is a letter or digit, or
5751 string of letters or digits, which specifies the type of debugging
5752 outputs desired. Normally these are used only for internal development
5753 or system debugging purposes. You can find full documentation for these
5754 switches in the body of the ``Debug`` unit in the compiler source
5755 file :file:`debug.adb`.
5758 .. index:: -gnatG (gcc)
5760 :switch:`-gnatG[={nn}]`
5761 This switch causes the compiler to generate auxiliary output containing
5762 a pseudo-source listing of the generated expanded code. Like most Ada
5763 compilers, GNAT works by first transforming the high level Ada code into
5764 lower level constructs. For example, tasking operations are transformed
5765 into calls to the tasking run-time routines. A unique capability of GNAT
5766 is to list this expanded code in a form very close to normal Ada source.
5767 This is very useful in understanding the implications of various Ada
5768 usage on the efficiency of the generated code. There are many cases in
5769 Ada (e.g., the use of controlled types), where simple Ada statements can
5770 generate a lot of run-time code. By using :switch:`-gnatG` you can identify
5771 these cases, and consider whether it may be desirable to modify the coding
5772 approach to improve efficiency.
5774 The optional parameter ``nn`` if present after -gnatG specifies an
5775 alternative maximum line length that overrides the normal default of 72.
5776 This value is in the range 40-999999, values less than 40 being silently
5777 reset to 40. The equal sign is optional.
5779 The format of the output is very similar to standard Ada source, and is
5780 easily understood by an Ada programmer. The following special syntactic
5781 additions correspond to low level features used in the generated code that
5782 do not have any exact analogies in pure Ada source form. The following
5783 is a partial list of these special constructions. See the spec
5784 of package ``Sprint`` in file :file:`sprint.ads` for a full list.
5786 .. index:: -gnatL (gcc)
5788 If the switch :switch:`-gnatL` is used in conjunction with
5789 :switch:`-gnatG`, then the original source lines are interspersed
5790 in the expanded source (as comment lines with the original line number).
5792 :samp:`new {xxx} [storage_pool = {yyy}]`
5793 Shows the storage pool being used for an allocator.
5796 :samp:`at end {procedure-name};`
5797 Shows the finalization (cleanup) procedure for a scope.
5800 :samp:`(if {expr} then {expr} else {expr})`
5801 Conditional expression equivalent to the ``x?y:z`` construction in C.
5804 :samp:`{target}^({source})`
5805 A conversion with floating-point truncation instead of rounding.
5808 :samp:`{target}?({source})`
5809 A conversion that bypasses normal Ada semantic checking. In particular
5810 enumeration types and fixed-point types are treated simply as integers.
5813 :samp:`{target}?^({source})`
5814 Combines the above two cases.
5819 :samp:`{x} #mod {y}`
5823 :samp:`{x} #rem {y}`
5824 A division or multiplication of fixed-point values which are treated as
5825 integers without any kind of scaling.
5828 :samp:`free {expr} [storage_pool = {xxx}]`
5829 Shows the storage pool associated with a ``free`` statement.
5832 :samp:`[subtype or type declaration]`
5833 Used to list an equivalent declaration for an internally generated
5834 type that is referenced elsewhere in the listing.
5837 :samp:`freeze {type-name} [{actions}]`
5838 Shows the point at which ``type-name`` is frozen, with possible
5839 associated actions to be performed at the freeze point.
5842 :samp:`reference {itype}`
5843 Reference (and hence definition) to internal type ``itype``.
5846 :samp:`{function-name}! ({arg}, {arg}, {arg})`
5847 Intrinsic function call.
5850 :samp:`{label-name} : label`
5851 Declaration of label ``labelname``.
5854 :samp:`#$ {subprogram-name}`
5855 An implicit call to a run-time support routine
5856 (to meet the requirement of H.3.1(9) in a
5860 :samp:`{expr} && {expr} && {expr} ... && {expr}`
5861 A multiple concatenation (same effect as ``expr`` & ``expr`` &
5862 ``expr``, but handled more efficiently).
5865 :samp:`[constraint_error]`
5866 Raise the ``Constraint_Error`` exception.
5869 :samp:`{expression}'reference`
5870 A pointer to the result of evaluating {expression}.
5873 :samp:`{target-type}!({source-expression})`
5874 An unchecked conversion of ``source-expression`` to ``target-type``.
5877 :samp:`[{numerator}/{denominator}]`
5878 Used to represent internal real literals (that) have no exact
5879 representation in base 2-16 (for example, the result of compile time
5880 evaluation of the expression 1.0/27.0).
5883 .. index:: -gnatD (gcc)
5885 :switch:`-gnatD[=nn]`
5886 When used in conjunction with :switch:`-gnatG`, this switch causes
5887 the expanded source, as described above for
5888 :switch:`-gnatG` to be written to files with names
5889 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
5890 instead of to the standard output file. For
5891 example, if the source file name is :file:`hello.adb`, then a file
5892 :file:`hello.adb.dg` will be written. The debugging
5893 information generated by the ``gcc`` :switch:`-g` switch
5894 will refer to the generated :file:`xxx.dg` file. This allows
5895 you to do source level debugging using the generated code which is
5896 sometimes useful for complex code, for example to find out exactly
5897 which part of a complex construction raised an exception. This switch
5898 also suppresses generation of cross-reference information (see
5899 :switch:`-gnatx`) since otherwise the cross-reference information
5900 would refer to the :file:`.dg` file, which would cause
5901 confusion since this is not the original source file.
5903 Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
5904 automatically, so it is not necessary to give both options.
5905 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
5907 .. index:: -gnatL (gcc)
5909 If the switch :switch:`-gnatL` is used in conjunction with
5910 :switch:`-gnatDG`, then the original source lines are interspersed
5911 in the expanded source (as comment lines with the original line number).
5913 The optional parameter ``nn`` if present after -gnatD specifies an
5914 alternative maximum line length that overrides the normal default of 72.
5915 This value is in the range 40-999999, values less than 40 being silently
5916 reset to 40. The equal sign is optional.
5919 .. index:: -gnatr (gcc)
5920 .. index:: pragma Restrictions
5923 This switch causes pragma Restrictions to be treated as Restriction_Warnings
5924 so that violation of restrictions causes warnings rather than illegalities.
5925 This is useful during the development process when new restrictions are added
5926 or investigated. The switch also causes pragma Profile to be treated as
5927 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
5928 restriction warnings rather than restrictions.
5931 .. index:: -gnatR (gcc)
5933 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
5934 This switch controls output from the compiler of a listing showing
5935 representation information for declared types, objects and subprograms.
5936 For :switch:`-gnatR0`, no information is output (equivalent to omitting
5937 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
5938 so :switch:`-gnatR` with no parameter has the same effect), size and
5939 alignment information is listed for declared array and record types.
5941 For :switch:`-gnatR2`, size and alignment information is listed for all
5942 declared types and objects. The ``Linker_Section`` is also listed for any
5943 entity for which the ``Linker_Section`` is set explicitly or implicitly (the
5944 latter case occurs for objects of a type for which a ``Linker_Section``
5947 For :switch:`-gnatR3`, symbolic expressions for values that are computed
5948 at run time for records are included. These symbolic expressions have
5949 a mostly obvious format with #n being used to represent the value of the
5950 n'th discriminant. See source files :file:`repinfo.ads/adb` in the
5951 GNAT sources for full details on the format of :switch:`-gnatR3` output.
5953 For :switch:`-gnatR4`, information for relevant compiler-generated types
5954 is also listed, i.e. when they are structurally part of other declared
5957 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
5958 extended representation information for record sub-components of records
5961 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
5962 subprogram conventions and parameter passing mechanisms for all the
5963 subprograms are included.
5965 If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
5966 the output is in the JSON data interchange format specified by the
5967 ECMA-404 standard. The semantic description of this JSON output is
5968 available in the specification of the Repinfo unit present in the
5971 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
5972 the output is to a file with the name :file:`file.rep` where ``file`` is
5973 the name of the corresponding source file, except if ``j`` is also
5974 specified, in which case the file name is :file:`file.json`.
5976 Note that it is possible for record components to have zero size. In
5977 this case, the component clause uses an obvious extension of permitted
5978 Ada syntax, for example ``at 0 range 0 .. -1``.
5981 .. index:: -gnatS (gcc)
5984 The use of the switch :switch:`-gnatS` for an
5985 Ada compilation will cause the compiler to output a
5986 representation of package Standard in a form very
5987 close to standard Ada. It is not quite possible to
5988 do this entirely in standard Ada (since new
5989 numeric base types cannot be created in standard
5990 Ada), but the output is easily
5991 readable to any Ada programmer, and is useful to
5992 determine the characteristics of target dependent
5993 types in package Standard.
5996 .. index:: -gnatx (gcc)
5999 Normally the compiler generates full cross-referencing information in
6000 the :file:`ALI` file. This information is used by a number of tools,
6001 including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch
6002 suppresses this information. This saves some space and may slightly
6003 speed up compilation, but means that these tools cannot be used.
6006 .. index:: -fgnat-encodings (gcc)
6008 :switch:`-fgnat-encodings=[all|gdb|minimal]`
6009 This switch controls the balance between GNAT encodings and standard DWARF
6010 emitted in the debug information.
6012 Historically, old debug formats like stabs were not powerful enough to
6013 express some Ada types (for instance, variant records or fixed-point types).
6014 To work around this, GNAT introduced proprietary encodings that embed the
6015 missing information ("GNAT encodings").
6017 Recent versions of the DWARF debug information format are now able to
6018 correctly describe most of these Ada constructs ("standard DWARF"). As
6019 third-party tools started to use this format, GNAT has been enhanced to
6020 generate it. However, most tools (including GDB) are still relying on GNAT
6023 To support all tools, GNAT needs to be versatile about the balance between
6024 generation of GNAT encodings and standard DWARF. This is what
6025 :switch:`-fgnat-encodings` is about.
6027 * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as
6028 possible so it does not conflict with GNAT encodings.
6029 * ``=gdb``: Emit as much standard DWARF as possible as long as the current
6030 GDB handles it. Emit GNAT encodings for the rest.
6031 * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT
6032 encodings for the rest.
6035 .. _Exception_Handling_Control:
6037 Exception Handling Control
6038 --------------------------
6040 GNAT uses two methods for handling exceptions at run time. The
6041 ``setjmp/longjmp`` method saves the context when entering
6042 a frame with an exception handler. Then when an exception is
6043 raised, the context can be restored immediately, without the
6044 need for tracing stack frames. This method provides very fast
6045 exception propagation, but introduces significant overhead for
6046 the use of exception handlers, even if no exception is raised.
6048 The other approach is called 'zero cost' exception handling.
6049 With this method, the compiler builds static tables to describe
6050 the exception ranges. No dynamic code is required when entering
6051 a frame containing an exception handler. When an exception is
6052 raised, the tables are used to control a back trace of the
6053 subprogram invocation stack to locate the required exception
6054 handler. This method has considerably poorer performance for
6055 the propagation of exceptions, but there is no overhead for
6056 exception handlers if no exception is raised. Note that in this
6057 mode and in the context of mixed Ada and C/C++ programming,
6058 to propagate an exception through a C/C++ code, the C/C++ code
6059 must be compiled with the :switch:`-funwind-tables` GCC's
6062 The following switches may be used to control which of the
6063 two exception handling methods is used.
6067 .. index:: --RTS=sjlj (gnatmake)
6069 :switch:`--RTS=sjlj`
6070 This switch causes the setjmp/longjmp run-time (when available) to be used
6071 for exception handling. If the default
6072 mechanism for the target is zero cost exceptions, then
6073 this switch can be used to modify this default, and must be
6074 used for all units in the partition.
6075 This option is rarely used. One case in which it may be
6076 advantageous is if you have an application where exception
6077 raising is common and the overall performance of the
6078 application is improved by favoring exception propagation.
6081 .. index:: --RTS=zcx (gnatmake)
6082 .. index:: Zero Cost Exceptions
6085 This switch causes the zero cost approach to be used
6086 for exception handling. If this is the default mechanism for the
6087 target (see below), then this switch is unneeded. If the default
6088 mechanism for the target is setjmp/longjmp exceptions, then
6089 this switch can be used to modify this default, and must be
6090 used for all units in the partition.
6091 This option can only be used if the zero cost approach
6092 is available for the target in use, otherwise it will generate an error.
6094 The same option :switch:`--RTS` must be used both for ``gcc``
6095 and ``gnatbind``. Passing this option to ``gnatmake``
6096 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
6097 through the compilation and binding steps.
6099 .. _Units_to_Sources_Mapping_Files:
6101 Units to Sources Mapping Files
6102 ------------------------------
6106 .. index:: -gnatem (gcc)
6108 :switch:`-gnatem={path}`
6109 A mapping file is a way to communicate to the compiler two mappings:
6110 from unit names to file names (without any directory information) and from
6111 file names to path names (with full directory information). These mappings
6112 are used by the compiler to short-circuit the path search.
6114 The use of mapping files is not required for correct operation of the
6115 compiler, but mapping files can improve efficiency, particularly when
6116 sources are read over a slow network connection. In normal operation,
6117 you need not be concerned with the format or use of mapping files,
6118 and the :switch:`-gnatem` switch is not a switch that you would use
6119 explicitly. It is intended primarily for use by automatic tools such as
6120 ``gnatmake`` running under the project file facility. The
6121 description here of the format of mapping files is provided
6122 for completeness and for possible use by other tools.
6124 A mapping file is a sequence of sets of three lines. In each set, the
6125 first line is the unit name, in lower case, with ``%s`` appended
6126 for specs and ``%b`` appended for bodies; the second line is the
6127 file name; and the third line is the path name.
6133 /gnat/project1/sources/main.2.ada
6136 When the switch :switch:`-gnatem` is specified, the compiler will
6137 create in memory the two mappings from the specified file. If there is
6138 any problem (nonexistent file, truncated file or duplicate entries),
6139 no mapping will be created.
6141 Several :switch:`-gnatem` switches may be specified; however, only the
6142 last one on the command line will be taken into account.
6144 When using a project file, ``gnatmake`` creates a temporary
6145 mapping file and communicates it to the compiler using this switch.
6148 .. _Code_Generation_Control:
6150 Code Generation Control
6151 -----------------------
6153 The GCC technology provides a wide range of target dependent
6154 :switch:`-m` switches for controlling
6155 details of code generation with respect to different versions of
6156 architectures. This includes variations in instruction sets (e.g.,
6157 different members of the power pc family), and different requirements
6158 for optimal arrangement of instructions (e.g., different members of
6159 the x86 family). The list of available :switch:`-m` switches may be
6160 found in the GCC documentation.
6162 Use of these :switch:`-m` switches may in some cases result in improved
6165 The GNAT technology is tested and qualified without any
6166 :switch:`-m` switches,
6167 so generally the most reliable approach is to avoid the use of these
6168 switches. However, we generally expect most of these switches to work
6169 successfully with GNAT, and many customers have reported successful
6170 use of these options.
6172 Our general advice is to avoid the use of :switch:`-m` switches unless
6173 special needs lead to requirements in this area. In particular,
6174 there is no point in using :switch:`-m` switches to improve performance
6175 unless you actually see a performance improvement.
6178 .. _Linker_Switches:
6183 Linker switches can be specified after :switch:`-largs` builder switch.
6185 .. index:: -fuse-ld=name
6187 :switch:`-fuse-ld={name}`
6188 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`,
6189 the alternative being ``gold`` for :file:`ld.gold`. The later is
6190 a more recent and faster linker, but only available on GNU/Linux
6193 .. _Binding_with_gnatbind:
6195 Binding with ``gnatbind``
6196 =========================
6198 .. index:: ! gnatbind
6200 This chapter describes the GNAT binder, ``gnatbind``, which is used
6201 to bind compiled GNAT objects.
6203 The ``gnatbind`` program performs four separate functions:
6205 * Checks that a program is consistent, in accordance with the rules in
6206 Chapter 10 of the Ada Reference Manual. In particular, error
6207 messages are generated if a program uses inconsistent versions of a
6210 * Checks that an acceptable order of elaboration exists for the program
6211 and issues an error message if it cannot find an order of elaboration
6212 that satisfies the rules in Chapter 10 of the Ada Language Manual.
6214 * Generates a main program incorporating the given elaboration order.
6215 This program is a small Ada package (body and spec) that
6216 must be subsequently compiled
6217 using the GNAT compiler. The necessary compilation step is usually
6218 performed automatically by ``gnatlink``. The two most important
6219 functions of this program
6220 are to call the elaboration routines of units in an appropriate order
6221 and to call the main program.
6223 * Determines the set of object files required by the given main program.
6224 This information is output in the forms of comments in the generated program,
6225 to be read by the ``gnatlink`` utility used to link the Ada application.
6227 .. _Running_gnatbind:
6229 Running ``gnatbind``
6230 --------------------
6232 The form of the ``gnatbind`` command is
6236 $ gnatbind [ switches ] mainprog[.ali] [ switches ]
6239 where :file:`mainprog.adb` is the Ada file containing the main program
6240 unit body. ``gnatbind`` constructs an Ada
6241 package in two files whose names are
6242 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
6243 For example, if given the
6244 parameter :file:`hello.ali`, for a main program contained in file
6245 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
6246 and :file:`b~hello.adb`.
6248 When doing consistency checking, the binder takes into consideration
6249 any source files it can locate. For example, if the binder determines
6250 that the given main program requires the package ``Pack``, whose
6252 file is :file:`pack.ali` and whose corresponding source spec file is
6253 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
6254 (using the same search path conventions as previously described for the
6255 ``gcc`` command). If it can locate this source file, it checks that
6257 or source checksums of the source and its references to in :file:`ALI` files
6258 match. In other words, any :file:`ALI` files that mentions this spec must have
6259 resulted from compiling this version of the source file (or in the case
6260 where the source checksums match, a version close enough that the
6261 difference does not matter).
6263 .. index:: Source files, use by binder
6265 The effect of this consistency checking, which includes source files, is
6266 that the binder ensures that the program is consistent with the latest
6267 version of the source files that can be located at bind time. Editing a
6268 source file without compiling files that depend on the source file cause
6269 error messages to be generated by the binder.
6271 For example, suppose you have a main program :file:`hello.adb` and a
6272 package ``P``, from file :file:`p.ads` and you perform the following
6275 * Enter ``gcc -c hello.adb`` to compile the main program.
6277 * Enter ``gcc -c p.ads`` to compile package ``P``.
6279 * Edit file :file:`p.ads`.
6281 * Enter ``gnatbind hello``.
6283 At this point, the file :file:`p.ali` contains an out-of-date time stamp
6284 because the file :file:`p.ads` has been edited. The attempt at binding
6285 fails, and the binder generates the following error messages:
6290 error: "hello.adb" must be recompiled ("p.ads" has been modified)
6291 error: "p.ads" has been modified and must be recompiled
6294 Now both files must be recompiled as indicated, and then the bind can
6295 succeed, generating a main program. You need not normally be concerned
6296 with the contents of this file, but for reference purposes a sample
6297 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6299 In most normal usage, the default mode of ``gnatbind`` which is to
6300 generate the main package in Ada, as described in the previous section.
6301 In particular, this means that any Ada programmer can read and understand
6302 the generated main program. It can also be debugged just like any other
6303 Ada code provided the :switch:`-g` switch is used for
6304 ``gnatbind`` and ``gnatlink``.
6306 .. _Switches_for_gnatbind:
6308 Switches for ``gnatbind``
6309 -------------------------
6311 The following switches are available with ``gnatbind``; details will
6312 be presented in subsequent sections.
6315 .. index:: --version (gnatbind)
6318 Display Copyright and version, then exit disregarding all other options.
6321 .. index:: --help (gnatbind)
6324 If :switch:`--version` was not used, display usage, then exit disregarding
6328 .. index:: -a (gnatbind)
6331 Indicates that, if supported by the platform, the adainit procedure should
6332 be treated as an initialisation routine by the linker (a constructor). This
6333 is intended to be used by the Project Manager to automatically initialize
6334 shared Stand-Alone Libraries.
6337 .. index:: -aO (gnatbind)
6340 Specify directory to be searched for ALI files.
6343 .. index:: -aI (gnatbind)
6346 Specify directory to be searched for source file.
6349 .. index:: -A (gnatbind)
6351 :switch:`-A[={filename}]`
6352 Output ALI list (to standard output or to the named file).
6355 .. index:: -b (gnatbind)
6358 Generate brief messages to :file:`stderr` even if verbose mode set.
6361 .. index:: -c (gnatbind)
6364 Check only, no generation of binder output file.
6367 .. index:: -dnn[k|m] (gnatbind)
6369 :switch:`-d{nn}[k|m]`
6370 This switch can be used to change the default task stack size value
6371 to a specified size ``nn``, which is expressed in bytes by default, or
6372 in kilobytes when suffixed with ``k`` or in megabytes when suffixed
6374 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6375 in effect, to completing all task specs with
6379 pragma Storage_Size (nn);
6381 When they do not already have such a pragma.
6384 .. index:: -D (gnatbind)
6386 :switch:`-D{nn}[k|m]`
6387 Set the default secondary stack size to ``nn``. The suffix indicates whether
6388 the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
6391 The secondary stack holds objects of unconstrained types that are returned by
6392 functions, for example unconstrained Strings. The size of the secondary stack
6393 can be dynamic or fixed depending on the target.
6395 For most targets, the secondary stack grows on demand and is implemented as
6396 a chain of blocks in the heap. In this case, the default secondary stack size
6397 determines the initial size of the secondary stack for each task and the
6398 smallest amount the secondary stack can grow by.
6400 For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
6401 fixed. This switch can be used to change the default size of these stacks.
6402 The default secondary stack size can be overridden on a per-task basis if
6403 individual tasks have different secondary stack requirements. This is
6404 achieved through the Secondary_Stack_Size aspect that takes the size of the
6405 secondary stack in bytes.
6407 .. index:: -e (gnatbind)
6410 Output complete list of elaboration-order dependencies.
6413 .. index:: -Ea (gnatbind)
6416 Store tracebacks in exception occurrences when the target supports it.
6417 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6418 unless symbolic tracebacks are enabled.
6420 See also the packages ``GNAT.Traceback`` and
6421 ``GNAT.Traceback.Symbolic`` for more information.
6422 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
6426 .. index:: -Es (gnatbind)
6429 Store tracebacks in exception occurrences when the target supports it.
6430 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6433 .. index:: -E (gnatbind)
6436 Currently the same as ``-Ea``.
6439 .. index:: -f (gnatbind)
6441 :switch:`-f{elab-order}`
6442 Force elaboration order. For further details see :ref:`Elaboration_Control`
6443 and :ref:`Elaboration_Order_Handling_in_GNAT`.
6446 .. index:: -F (gnatbind)
6449 Force the checks of elaboration flags. ``gnatbind`` does not normally
6450 generate checks of elaboration flags for the main executable, except when
6451 a Stand-Alone Library is used. However, there are cases when this cannot be
6452 detected by gnatbind. An example is importing an interface of a Stand-Alone
6453 Library through a pragma Import and only specifying through a linker switch
6454 this Stand-Alone Library. This switch is used to guarantee that elaboration
6455 flag checks are generated.
6458 .. index:: -h (gnatbind)
6461 Output usage (help) information.
6464 .. index:: -H (gnatbind)
6467 Legacy elaboration order model enabled. For further details see
6468 :ref:`Elaboration_Order_Handling_in_GNAT`.
6471 .. index:: -H32 (gnatbind)
6474 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
6475 For further details see :ref:`Dynamic_Allocation_Control`.
6478 .. index:: -H64 (gnatbind)
6479 .. index:: __gnat_malloc
6482 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
6483 For further details see :ref:`Dynamic_Allocation_Control`.
6486 .. index:: -I (gnatbind)
6489 Specify directory to be searched for source and ALI files.
6492 .. index:: -I- (gnatbind)
6495 Do not look for sources in the current directory where ``gnatbind`` was
6496 invoked, and do not look for ALI files in the directory containing the
6497 ALI file named in the ``gnatbind`` command line.
6500 .. index:: -l (gnatbind)
6503 Output chosen elaboration order.
6506 .. index:: -L (gnatbind)
6509 Bind the units for library building. In this case the ``adainit`` and
6510 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6511 are renamed to :samp:`{xxx}init` and
6514 (:ref:`GNAT_and_Libraries`, for more details.)
6517 .. index:: -M (gnatbind)
6520 Rename generated main program from main to xyz. This option is
6521 supported on cross environments only.
6523 .. index:: -m (gnatbind)
6526 Limit number of detected errors or warnings to ``n``, where ``n`` is
6527 in the range 1..999999. The default value if no switch is
6528 given is 9999. If the number of warnings reaches this limit, then a
6529 message is output and further warnings are suppressed, the bind
6530 continues in this case. If the number of errors reaches this
6531 limit, then a message is output and the bind is abandoned.
6532 A value of zero means that no limit is enforced. The equal
6535 .. index:: -minimal (gnatbind)
6538 Generate a binder file suitable for space-constrained applications. When
6539 active, binder-generated objects not required for program operation are no
6540 longer generated. **Warning:** this option comes with the following
6543 * Starting the program's execution in the debugger will cause it to
6544 stop at the start of the ``main`` function instead of the main subprogram.
6545 This can be worked around by manually inserting a breakpoint on that
6546 subprogram and resuming the program's execution until reaching that breakpoint.
6547 * Programs using GNAT.Compiler_Version will not link.
6549 .. index:: -n (gnatbind)
6555 .. index:: -nostdinc (gnatbind)
6558 Do not look for sources in the system default directory.
6561 .. index:: -nostdlib (gnatbind)
6564 Do not look for library files in the system default directory.
6567 .. index:: --RTS (gnatbind)
6569 :switch:`--RTS={rts-path}`
6570 Specifies the default location of the run-time library. Same meaning as the
6571 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
6573 .. index:: -o (gnatbind)
6576 Name the output file ``file`` (default is :file:`b~`xxx`.adb`).
6577 Note that if this option is used, then linking must be done manually,
6578 gnatlink cannot be used.
6581 .. index:: -O (gnatbind)
6583 :switch:`-O[={filename}]`
6584 Output object list (to standard output or to the named file).
6587 .. index:: -p (gnatbind)
6590 Pessimistic (worst-case) elaboration order.
6593 .. index:: -P (gnatbind)
6596 Generate binder file suitable for CodePeer.
6599 .. index:: -R (gnatbind)
6602 Output closure source list, which includes all non-run-time units that are
6603 included in the bind.
6606 .. index:: -Ra (gnatbind)
6609 Like :switch:`-R` but the list includes run-time units.
6612 .. index:: -s (gnatbind)
6615 Require all source files to be present.
6618 .. index:: -S (gnatbind)
6621 Specifies the value to be used when detecting uninitialized scalar
6622 objects with pragma Initialize_Scalars.
6623 The ``xxx`` string specified with the switch is one of:
6625 * ``in`` for an invalid value.
6627 If zero is invalid for the discrete type in question,
6628 then the scalar value is set to all zero bits.
6629 For signed discrete types, the largest possible negative value of
6630 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6631 For unsigned discrete types, the underlying scalar value is set to all
6632 one bits. For floating-point types, a NaN value is set
6633 (see body of package System.Scalar_Values for exact values).
6635 * ``lo`` for low value.
6637 If zero is invalid for the discrete type in question,
6638 then the scalar value is set to all zero bits.
6639 For signed discrete types, the largest possible negative value of
6640 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6641 For unsigned discrete types, the underlying scalar value is set to all
6642 zero bits. For floating-point, a small value is set
6643 (see body of package System.Scalar_Values for exact values).
6645 * ``hi`` for high value.
6647 If zero is invalid for the discrete type in question,
6648 then the scalar value is set to all one bits.
6649 For signed discrete types, the largest possible positive value of
6650 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6651 For unsigned discrete types, the underlying scalar value is set to all
6652 one bits. For floating-point, a large value is set
6653 (see body of package System.Scalar_Values for exact values).
6655 * ``xx`` for hex value (two hex digits).
6657 The underlying scalar is set to a value consisting of repeated bytes, whose
6658 value corresponds to the given value. For example if ``BF`` is given,
6659 then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``.
6661 .. index:: GNAT_INIT_SCALARS
6663 In addition, you can specify :switch:`-Sev` to indicate that the value is
6664 to be set at run time. In this case, the program will look for an environment
6665 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
6666 of :samp:`in/lo/hi/{xx}` with the same meanings as above.
6667 If no environment variable is found, or if it does not have a valid value,
6668 then the default is ``in`` (invalid values).
6670 .. index:: -static (gnatbind)
6673 Link against a static GNAT run-time.
6676 .. index:: -shared (gnatbind)
6679 Link against a shared GNAT run-time when available.
6682 .. index:: -t (gnatbind)
6685 Tolerate time stamp and other consistency errors.
6688 .. index:: -T (gnatbind)
6691 Set the time slice value to ``n`` milliseconds. If the system supports
6692 the specification of a specific time slice value, then the indicated value
6693 is used. If the system does not support specific time slice values, but
6694 does support some general notion of round-robin scheduling, then any
6695 nonzero value will activate round-robin scheduling.
6697 A value of zero is treated specially. It turns off time
6698 slicing, and in addition, indicates to the tasking run-time that the
6699 semantics should match as closely as possible the Annex D
6700 requirements of the Ada RM, and in particular sets the default
6701 scheduling policy to ``FIFO_Within_Priorities``.
6704 .. index:: -u (gnatbind)
6707 Enable dynamic stack usage, with ``n`` results stored and displayed
6708 at program termination. A result is generated when a task
6709 terminates. Results that can't be stored are displayed on the fly, at
6710 task termination. This option is currently not supported on Itanium
6711 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6714 .. index:: -v (gnatbind)
6717 Verbose mode. Write error messages, header, summary output to
6721 .. index:: -V (gnatbind)
6723 :switch:`-V{key}={value}`
6724 Store the given association of ``key`` to ``value`` in the bind environment.
6725 Values stored this way can be retrieved at run time using
6726 ``GNAT.Bind_Environment``.
6729 .. index:: -w (gnatbind)
6732 Warning mode; ``x`` = s/e for suppress/treat as error.
6735 .. index:: -Wx (gnatbind)
6738 Override default wide character encoding for standard Text_IO files.
6741 .. index:: -x (gnatbind)
6744 Exclude source files (check object consistency only).
6747 .. index:: -Xnnn (gnatbind)
6750 Set default exit status value, normally 0 for POSIX compliance.
6753 .. index:: -y (gnatbind)
6756 Enable leap seconds support in ``Ada.Calendar`` and its children.
6759 .. index:: -z (gnatbind)
6764 You may obtain this listing of switches by running ``gnatbind`` with
6768 .. _Consistency-Checking_Modes:
6770 Consistency-Checking Modes
6771 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6773 As described earlier, by default ``gnatbind`` checks
6774 that object files are consistent with one another and are consistent
6775 with any source files it can locate. The following switches control binder
6779 .. index:: -s (gnatbind)
6782 Require source files to be present. In this mode, the binder must be
6783 able to locate all source files that are referenced, in order to check
6784 their consistency. In normal mode, if a source file cannot be located it
6785 is simply ignored. If you specify this switch, a missing source
6789 .. index:: -Wx (gnatbind)
6792 Override default wide character encoding for standard Text_IO files.
6793 Normally the default wide character encoding method used for standard
6794 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6795 the main source input (see description of switch
6796 :switch:`-gnatWx` for the compiler). The
6797 use of this switch for the binder (which has the same set of
6798 possible arguments) overrides this default as specified.
6801 .. index:: -x (gnatbind)
6804 Exclude source files. In this mode, the binder only checks that ALI
6805 files are consistent with one another. Source files are not accessed.
6806 The binder runs faster in this mode, and there is still a guarantee that
6807 the resulting program is self-consistent.
6808 If a source file has been edited since it was last compiled, and you
6809 specify this switch, the binder will not detect that the object
6810 file is out of date with respect to the source file. Note that this is the
6811 mode that is automatically used by ``gnatmake`` because in this
6812 case the checking against sources has already been performed by
6813 ``gnatmake`` in the course of compilation (i.e., before binding).
6816 .. _Binder_Error_Message_Control:
6818 Binder Error Message Control
6819 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6821 The following switches provide control over the generation of error
6822 messages from the binder:
6826 .. index:: -v (gnatbind)
6829 Verbose mode. In the normal mode, brief error messages are generated to
6830 :file:`stderr`. If this switch is present, a header is written
6831 to :file:`stdout` and any error messages are directed to :file:`stdout`.
6832 All that is written to :file:`stderr` is a brief summary message.
6835 .. index:: -b (gnatbind)
6838 Generate brief error messages to :file:`stderr` even if verbose mode is
6839 specified. This is relevant only when used with the
6840 :switch:`-v` switch.
6843 .. index:: -m (gnatbind)
6846 Limits the number of error messages to ``n``, a decimal integer in the
6847 range 1-999. The binder terminates immediately if this limit is reached.
6850 .. index:: -M (gnatbind)
6853 Renames the generated main program from ``main`` to ``xxx``.
6854 This is useful in the case of some cross-building environments, where
6855 the actual main program is separate from the one generated
6859 .. index:: -ws (gnatbind)
6863 Suppress all warning messages.
6866 .. index:: -we (gnatbind)
6869 Treat any warning messages as fatal errors.
6872 .. index:: -t (gnatbind)
6873 .. index:: Time stamp checks, in binder
6874 .. index:: Binder consistency checks
6875 .. index:: Consistency checks, in binder
6878 The binder performs a number of consistency checks including:
6881 * Check that time stamps of a given source unit are consistent
6883 * Check that checksums of a given source unit are consistent
6885 * Check that consistent versions of ``GNAT`` were used for compilation
6887 * Check consistency of configuration pragmas as required
6889 Normally failure of such checks, in accordance with the consistency
6890 requirements of the Ada Reference Manual, causes error messages to be
6891 generated which abort the binder and prevent the output of a binder
6892 file and subsequent link to obtain an executable.
6894 The :switch:`-t` switch converts these error messages
6895 into warnings, so that
6896 binding and linking can continue to completion even in the presence of such
6897 errors. The result may be a failed link (due to missing symbols), or a
6898 non-functional executable which has undefined semantics.
6902 This means that :switch:`-t` should be used only in unusual situations,
6905 .. _Elaboration_Control:
6910 The following switches provide additional control over the elaboration
6911 order. For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
6914 .. index:: -f (gnatbind)
6916 :switch:`-f{elab-order}`
6917 Force elaboration order.
6919 ``elab-order`` should be the name of a "forced elaboration order file", that
6920 is, a text file containing library item names, one per line. A name of the
6921 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
6922 name of the form "some.unit%b" or "some.unit (body)" denotes the body of
6923 Some.Unit. Each pair of lines is taken to mean that there is an elaboration
6924 dependence of the second line on the first. For example, if the file
6934 then the spec of This will be elaborated before the body of This, and the
6935 body of This will be elaborated before the spec of That, and the spec of That
6936 will be elaborated before the body of That. The first and last of these three
6937 dependences are already required by Ada rules, so this file is really just
6938 forcing the body of This to be elaborated before the spec of That.
6940 The given order must be consistent with Ada rules, or else ``gnatbind`` will
6941 give elaboration cycle errors. For example, if you say x (body) should be
6942 elaborated before x (spec), there will be a cycle, because Ada rules require
6943 x (spec) to be elaborated before x (body); you can't have the spec and body
6944 both elaborated before each other.
6946 If you later add "with That;" to the body of This, there will be a cycle, in
6947 which case you should erase either "this (body)" or "that (spec)" from the
6948 above forced elaboration order file.
6950 Blank lines and Ada-style comments are ignored. Unit names that do not exist
6951 in the program are ignored. Units in the GNAT predefined library are also
6955 .. index:: -p (gnatbind)
6958 Pessimistic elaboration order
6960 This switch is only applicable to the pre-20.x legacy elaboration models.
6961 The post-20.x elaboration model uses a more informed approach of ordering
6964 Normally the binder attempts to choose an elaboration order that is likely to
6965 minimize the likelihood of an elaboration order error resulting in raising a
6966 ``Program_Error`` exception. This switch reverses the action of the binder,
6967 and requests that it deliberately choose an order that is likely to maximize
6968 the likelihood of an elaboration error. This is useful in ensuring
6969 portability and avoiding dependence on accidental fortuitous elaboration
6972 Normally it only makes sense to use the :switch:`-p` switch if dynamic
6973 elaboration checking is used (:switch:`-gnatE` switch used for compilation).
6974 This is because in the default static elaboration mode, all necessary
6975 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
6976 These implicit pragmas are still respected by the binder in :switch:`-p`
6977 mode, so a safe elaboration order is assured.
6979 Note that :switch:`-p` is not intended for production use; it is more for
6980 debugging/experimental use.
6987 The following switches allow additional control over the output
6988 generated by the binder.
6991 .. index:: -c (gnatbind)
6994 Check only. Do not generate the binder output file. In this mode the
6995 binder performs all error checks but does not generate an output file.
6998 .. index:: -e (gnatbind)
7001 Output complete list of elaboration-order dependencies, showing the
7002 reason for each dependency. This output can be rather extensive but may
7003 be useful in diagnosing problems with elaboration order. The output is
7004 written to :file:`stdout`.
7007 .. index:: -h (gnatbind)
7010 Output usage information. The output is written to :file:`stdout`.
7013 .. index:: -K (gnatbind)
7016 Output linker options to :file:`stdout`. Includes library search paths,
7017 contents of pragmas Ident and Linker_Options, and libraries added
7021 .. index:: -l (gnatbind)
7024 Output chosen elaboration order. The output is written to :file:`stdout`.
7027 .. index:: -O (gnatbind)
7030 Output full names of all the object files that must be linked to provide
7031 the Ada component of the program. The output is written to :file:`stdout`.
7032 This list includes the files explicitly supplied and referenced by the user
7033 as well as implicitly referenced run-time unit files. The latter are
7034 omitted if the corresponding units reside in shared libraries. The
7035 directory names for the run-time units depend on the system configuration.
7038 .. index:: -o (gnatbind)
7041 Set name of output file to ``file`` instead of the normal
7042 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
7043 binder generated body filename.
7044 Note that if this option is used, then linking must be done manually.
7045 It is not possible to use gnatlink in this case, since it cannot locate
7049 .. index:: -r (gnatbind)
7052 Generate list of ``pragma Restrictions`` that could be applied to
7053 the current unit. This is useful for code audit purposes, and also may
7054 be used to improve code generation in some cases.
7057 .. _Dynamic_Allocation_Control:
7059 Dynamic Allocation Control
7060 ^^^^^^^^^^^^^^^^^^^^^^^^^^
7062 The heap control switches -- :switch:`-H32` and :switch:`-H64` --
7063 determine whether dynamic allocation uses 32-bit or 64-bit memory.
7064 They only affect compiler-generated allocations via ``__gnat_malloc``;
7065 explicit calls to ``malloc`` and related functions from the C
7066 run-time library are unaffected.
7069 Allocate memory on 32-bit heap
7073 Allocate memory on 64-bit heap. This is the default
7074 unless explicitly overridden by a ``'Size`` clause on the access type.
7076 These switches are only effective on VMS platforms.
7079 .. _Binding_with_Non-Ada_Main_Programs:
7081 Binding with Non-Ada Main Programs
7082 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7084 The description so far has assumed that the main
7085 program is in Ada, and that the task of the binder is to generate a
7086 corresponding function ``main`` that invokes this Ada main
7087 program. GNAT also supports the building of executable programs where
7088 the main program is not in Ada, but some of the called routines are
7089 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
7090 The following switch is used in this situation:
7093 .. index:: -n (gnatbind)
7096 No main program. The main program is not in Ada.
7098 In this case, most of the functions of the binder are still required,
7099 but instead of generating a main program, the binder generates a file
7100 containing the following callable routines:
7105 You must call this routine to initialize the Ada part of the program by
7106 calling the necessary elaboration routines. A call to ``adainit`` is
7107 required before the first call to an Ada subprogram.
7109 Note that it is assumed that the basic execution environment must be setup
7110 to be appropriate for Ada execution at the point where the first Ada
7111 subprogram is called. In particular, if the Ada code will do any
7112 floating-point operations, then the FPU must be setup in an appropriate
7113 manner. For the case of the x86, for example, full precision mode is
7114 required. The procedure GNAT.Float_Control.Reset may be used to ensure
7115 that the FPU is in the right state.
7120 You must call this routine to perform any library-level finalization
7121 required by the Ada subprograms. A call to ``adafinal`` is required
7122 after the last call to an Ada subprogram, and before the program
7125 .. index:: -n (gnatbind)
7126 .. index:: Binder, multiple input files
7128 If the :switch:`-n` switch
7129 is given, more than one ALI file may appear on
7130 the command line for ``gnatbind``. The normal ``closure``
7131 calculation is performed for each of the specified units. Calculating
7132 the closure means finding out the set of units involved by tracing
7133 |with| references. The reason it is necessary to be able to
7134 specify more than one ALI file is that a given program may invoke two or
7135 more quite separate groups of Ada units.
7137 The binder takes the name of its output file from the last specified ALI
7138 file, unless overridden by the use of the :switch:`-o file`.
7140 .. index:: -o (gnatbind)
7142 The output is an Ada unit in source form that can be compiled with GNAT.
7143 This compilation occurs automatically as part of the ``gnatlink``
7146 Currently the GNAT run-time requires a FPU using 80 bits mode
7147 precision. Under targets where this is not the default it is required to
7148 call GNAT.Float_Control.Reset before using floating point numbers (this
7149 include float computation, float input and output) in the Ada code. A
7150 side effect is that this could be the wrong mode for the foreign code
7151 where floating point computation could be broken after this call.
7154 .. _Binding_Programs_with_No_Main_Subprogram:
7156 Binding Programs with No Main Subprogram
7157 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7159 It is possible to have an Ada program which does not have a main
7160 subprogram. This program will call the elaboration routines of all the
7161 packages, then the finalization routines.
7163 The following switch is used to bind programs organized in this manner:
7165 .. index:: -z (gnatbind)
7168 Normally the binder checks that the unit name given on the command line
7169 corresponds to a suitable main subprogram. When this switch is used,
7170 a list of ALI files can be given, and the execution of the program
7171 consists of elaboration of these units in an appropriate order. Note
7172 that the default wide character encoding method for standard Text_IO
7173 files is always set to Brackets if this switch is set (you can use
7175 :switch:`-Wx` to override this default).
7178 .. _Command-Line_Access:
7183 The package ``Ada.Command_Line`` provides access to the command-line
7184 arguments and program name. In order for this interface to operate
7185 correctly, the two variables
7192 .. index:: gnat_argv
7193 .. index:: gnat_argc
7195 are declared in one of the GNAT library routines. These variables must
7196 be set from the actual ``argc`` and ``argv`` values passed to the
7197 main program. With no *n* present, ``gnatbind``
7198 generates the C main program to automatically set these variables.
7199 If the *n* switch is used, there is no automatic way to
7200 set these variables. If they are not set, the procedures in
7201 ``Ada.Command_Line`` will not be available, and any attempt to use
7202 them will raise ``Constraint_Error``. If command line access is
7203 required, your main program must set ``gnat_argc`` and
7204 ``gnat_argv`` from the ``argc`` and ``argv`` values passed to
7208 .. _Search_Paths_for_gnatbind:
7210 Search Paths for ``gnatbind``
7211 -----------------------------
7213 The binder takes the name of an ALI file as its argument and needs to
7214 locate source files as well as other ALI files to verify object consistency.
7216 For source files, it follows exactly the same search rules as ``gcc``
7217 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
7218 directories searched are:
7220 * The directory containing the ALI file named in the command line, unless
7221 the switch :switch:`-I-` is specified.
7223 * All directories specified by :switch:`-I`
7224 switches on the ``gnatbind``
7225 command line, in the order given.
7227 .. index:: ADA_PRJ_OBJECTS_FILE
7229 * Each of the directories listed in the text file whose name is given
7230 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
7232 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
7233 driver when project files are used. It should not normally be set
7236 .. index:: ADA_OBJECTS_PATH
7238 * Each of the directories listed in the value of the
7239 :envvar:`ADA_OBJECTS_PATH` environment variable.
7240 Construct this value
7241 exactly as the :envvar:`PATH` environment variable: a list of directory
7242 names separated by colons (semicolons when working with the NT version
7245 * The content of the :file:`ada_object_path` file which is part of the GNAT
7246 installation tree and is used to store standard libraries such as the
7247 GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
7248 specified. See :ref:`Installing_a_library`
7250 .. index:: -I (gnatbind)
7251 .. index:: -aI (gnatbind)
7252 .. index:: -aO (gnatbind)
7254 In the binder the switch :switch:`-I`
7255 is used to specify both source and
7256 library file paths. Use :switch:`-aI`
7257 instead if you want to specify
7258 source paths only, and :switch:`-aO`
7259 if you want to specify library paths
7260 only. This means that for the binder
7261 :switch:`-I{dir}` is equivalent to
7263 :switch:`-aO`{dir}`.
7264 The binder generates the bind file (a C language source file) in the
7265 current working directory.
7269 .. index:: Interfaces
7272 The packages ``Ada``, ``System``, and ``Interfaces`` and their
7273 children make up the GNAT Run-Time Library, together with the package
7274 GNAT and its children, which contain a set of useful additional
7275 library functions provided by GNAT. The sources for these units are
7276 needed by the compiler and are kept together in one directory. The ALI
7277 files and object files generated by compiling the RTL are needed by the
7278 binder and the linker and are kept together in one directory, typically
7279 different from the directory containing the sources. In a normal
7280 installation, you need not specify these directory names when compiling
7281 or binding. Either the environment variables or the built-in defaults
7282 cause these files to be found.
7284 Besides simplifying access to the RTL, a major use of search paths is
7285 in compiling sources from multiple directories. This can make
7286 development environments much more flexible.
7289 .. _Examples_of_gnatbind_Usage:
7291 Examples of ``gnatbind`` Usage
7292 ------------------------------
7294 Here are some examples of ``gnatbind`` invovations:
7300 The main program ``Hello`` (source program in :file:`hello.adb`) is
7301 bound using the standard switch settings. The generated main program is
7302 :file:`b~hello.adb`. This is the normal, default use of the binder.
7306 gnatbind hello -o mainprog.adb
7308 The main program ``Hello`` (source program in :file:`hello.adb`) is
7309 bound using the standard switch settings. The generated main program is
7310 :file:`mainprog.adb` with the associated spec in
7311 :file:`mainprog.ads`. Note that you must specify the body here not the
7312 spec. Note that if this option is used, then linking must be done manually,
7313 since gnatlink will not be able to find the generated file.
7316 .. _Linking_with_gnatlink:
7318 Linking with ``gnatlink``
7319 =========================
7321 .. index:: ! gnatlink
7323 This chapter discusses ``gnatlink``, a tool that links
7324 an Ada program and builds an executable file. This utility
7325 invokes the system linker (via the ``gcc`` command)
7326 with a correct list of object files and library references.
7327 ``gnatlink`` automatically determines the list of files and
7328 references for the Ada part of a program. It uses the binder file
7329 generated by the ``gnatbind`` to determine this list.
7331 .. _Running_gnatlink:
7333 Running ``gnatlink``
7334 --------------------
7336 The form of the ``gnatlink`` command is
7341 $ gnatlink [ switches ] mainprog [.ali]
7342 [ non-Ada objects ] [ linker options ]
7346 The arguments of ``gnatlink`` (switches, main ``ALI`` file,
7348 or linker options) may be in any order, provided that no non-Ada object may
7349 be mistaken for a main :file:`ALI` file.
7350 Any file name :file:`F` without the :file:`.ali`
7351 extension will be taken as the main :file:`ALI` file if a file exists
7352 whose name is the concatenation of :file:`F` and :file:`.ali`.
7354 :file:`mainprog.ali` references the ALI file of the main program.
7355 The :file:`.ali` extension of this file can be omitted. From this
7356 reference, ``gnatlink`` locates the corresponding binder file
7357 :file:`b~mainprog.adb` and, using the information in this file along
7358 with the list of non-Ada objects and linker options, constructs a
7359 linker command file to create the executable.
7361 The arguments other than the ``gnatlink`` switches and the main
7362 :file:`ALI` file are passed to the linker uninterpreted.
7363 They typically include the names of
7364 object files for units written in other languages than Ada and any library
7365 references required to resolve references in any of these foreign language
7366 units, or in ``Import`` pragmas in any Ada units.
7368 ``linker options`` is an optional list of linker specific
7370 The default linker called by gnatlink is ``gcc`` which in
7371 turn calls the appropriate system linker.
7373 One useful option for the linker is :switch:`-s`: it reduces the size of the
7374 executable by removing all symbol table and relocation information from the
7377 Standard options for the linker such as :switch:`-lmy_lib` or
7378 :switch:`-Ldir` can be added as is.
7379 For options that are not recognized by
7380 ``gcc`` as linker options, use the ``gcc`` switches
7381 :switch:`-Xlinker` or :switch:`-Wl,`.
7383 Refer to the GCC documentation for
7386 Here is an example showing how to generate a linker map:
7390 $ gnatlink my_prog -Wl,-Map,MAPFILE
7393 Using ``linker options`` it is possible to set the program stack and
7395 See :ref:`Setting_Stack_Size_from_gnatlink` and
7396 :ref:`Setting_Heap_Size_from_gnatlink`.
7398 ``gnatlink`` determines the list of objects required by the Ada
7399 program and prepends them to the list of objects passed to the linker.
7400 ``gnatlink`` also gathers any arguments set by the use of
7401 ``pragma Linker_Options`` and adds them to the list of arguments
7402 presented to the linker.
7405 .. _Switches_for_gnatlink:
7407 Switches for ``gnatlink``
7408 -------------------------
7410 The following switches are available with the ``gnatlink`` utility:
7412 .. index:: --version (gnatlink)
7415 Display Copyright and version, then exit disregarding all other options.
7418 .. index:: --help (gnatlink)
7421 If :switch:`--version` was not used, display usage, then exit disregarding
7425 .. index:: Command line length
7426 .. index:: -f (gnatlink)
7429 On some targets, the command line length is limited, and ``gnatlink``
7430 will generate a separate file for the linker if the list of object files
7432 The :switch:`-f` switch forces this file
7433 to be generated even if
7434 the limit is not exceeded. This is useful in some cases to deal with
7435 special situations where the command line length is exceeded.
7438 .. index:: Debugging information, including
7439 .. index:: -g (gnatlink)
7442 The option to include debugging information causes the Ada bind file (in
7443 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
7444 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7445 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7446 Without :switch:`-g`, the binder removes these files by default.
7448 .. index:: -n (gnatlink)
7451 Do not compile the file generated by the binder. This may be used when
7452 a link is rerun with different options, but there is no need to recompile
7456 .. index:: -v (gnatlink)
7459 Verbose mode. Causes additional information to be output, including a full
7460 list of the included object files.
7461 This switch option is most useful when you want
7462 to see what set of object files are being used in the link step.
7465 .. index:: -v -v (gnatlink)
7468 Very verbose mode. Requests that the compiler operate in verbose mode when
7469 it compiles the binder file, and that the system linker run in verbose mode.
7472 .. index:: -o (gnatlink)
7474 :switch:`-o {exec-name}`
7475 ``exec-name`` specifies an alternate name for the generated
7476 executable program. If this switch is omitted, the executable has the same
7477 name as the main unit. For example, ``gnatlink try.ali`` creates
7478 an executable called :file:`try`.
7481 .. index:: -B (gnatlink)
7484 Load compiler executables (for example, ``gnat1``, the Ada compiler)
7485 from ``dir`` instead of the default location. Only use this switch
7486 when multiple versions of the GNAT compiler are available.
7487 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
7488 for further details. You would normally use the :switch:`-b` or
7489 :switch:`-V` switch instead.
7492 .. index:: -M (gnatlink)
7495 When linking an executable, create a map file. The name of the map file
7496 has the same name as the executable with extension ".map".
7499 .. index:: -M= (gnatlink)
7501 :switch:`-M={mapfile}`
7502 When linking an executable, create a map file. The name of the map file is
7506 .. index:: --GCC=compiler_name (gnatlink)
7508 :switch:`--GCC={compiler_name}`
7509 Program used for compiling the binder file. The default is
7510 ``gcc``. You need to use quotes around ``compiler_name`` if
7511 ``compiler_name`` contains spaces or other separator characters.
7512 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
7513 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7514 inserted after your command name. Thus in the above example the compiler
7515 command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
7516 A limitation of this syntax is that the name and path name of the executable
7517 itself must not include any embedded spaces. If the compiler executable is
7518 different from the default one (gcc or <prefix>-gcc), then the back-end
7519 switches in the ALI file are not used to compile the binder generated source.
7520 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7521 switches will be used for ``--GCC="gcc -gnatv"``. If several
7522 ``--GCC=compiler_name`` are used, only the last ``compiler_name``
7523 is taken into account. However, all the additional switches are also taken
7525 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7526 ``--GCC="bar -x -y -z -t"``.
7529 .. index:: --LINK= (gnatlink)
7531 :switch:`--LINK={name}`
7532 ``name`` is the name of the linker to be invoked. This is especially
7533 useful in mixed language programs since languages such as C++ require
7534 their own linker to be used. When this switch is omitted, the default
7535 name for the linker is ``gcc``. When this switch is used, the
7536 specified linker is called instead of ``gcc`` with exactly the same
7537 parameters that would have been passed to ``gcc`` so if the desired
7538 linker requires different parameters it is necessary to use a wrapper
7539 script that massages the parameters before invoking the real linker. It
7540 may be useful to control the exact invocation by using the verbose
7544 .. _Using_the_GNU_make_Utility:
7546 Using the GNU ``make`` Utility
7547 ==============================
7549 .. index:: make (GNU), GNU make
7551 This chapter offers some examples of makefiles that solve specific
7552 problems. It does not explain how to write a makefile, nor does it try to replace the
7553 ``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7555 All the examples in this section are specific to the GNU version of
7556 make. Although ``make`` is a standard utility, and the basic language
7557 is the same, these examples use some advanced features found only in
7560 .. _Using_gnatmake_in_a_Makefile:
7562 Using gnatmake in a Makefile
7563 ----------------------------
7565 .. index makefile (GNU make)
7567 Complex project organizations can be handled in a very powerful way by
7568 using GNU make combined with gnatmake. For instance, here is a Makefile
7569 which allows you to build each subsystem of a big project into a separate
7570 shared library. Such a makefile allows you to significantly reduce the link
7571 time of very big applications while maintaining full coherence at
7572 each step of the build process.
7574 The list of dependencies are handled automatically by
7575 ``gnatmake``. The Makefile is simply used to call gnatmake in each of
7576 the appropriate directories.
7578 Note that you should also read the example on how to automatically
7579 create the list of directories
7580 (:ref:`Automatically_Creating_a_List_of_Directories`)
7581 which might help you in case your project has a lot of subdirectories.
7584 .. code-block:: makefile
7586 ## This Makefile is intended to be used with the following directory
7588 ## - The sources are split into a series of csc (computer software components)
7589 ## Each of these csc is put in its own directory.
7590 ## Their name are referenced by the directory names.
7591 ## They will be compiled into shared library (although this would also work
7592 ## with static libraries
7593 ## - The main program (and possibly other packages that do not belong to any
7594 ## csc is put in the top level directory (where the Makefile is).
7595 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7596 ## \\_ second_csc (sources) __ lib (will contain the library)
7598 ## Although this Makefile is build for shared library, it is easy to modify
7599 ## to build partial link objects instead (modify the lines with -shared and
7602 ## With this makefile, you can change any file in the system or add any new
7603 ## file, and everything will be recompiled correctly (only the relevant shared
7604 ## objects will be recompiled, and the main program will be re-linked).
7606 # The list of computer software component for your project. This might be
7607 # generated automatically.
7610 # Name of the main program (no extension)
7613 # If we need to build objects with -fPIC, uncomment the following line
7616 # The following variable should give the directory containing libgnat.so
7617 # You can get this directory through 'gnatls -v'. This is usually the last
7618 # directory in the Object_Path.
7621 # The directories for the libraries
7622 # (This macro expands the list of CSC to the list of shared libraries, you
7623 # could simply use the expanded form:
7624 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7625 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7627 ${MAIN}: objects ${LIB_DIR}
7628 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7629 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7632 # recompile the sources
7633 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7635 # Note: In a future version of GNAT, the following commands will be simplified
7636 # by a new tool, gnatmlib
7639 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7640 cd ${dir $@ } && cp -f ../*.ali .
7642 # The dependencies for the modules
7643 # Note that we have to force the expansion of *.o, since in some cases
7644 # make won't be able to do it itself.
7645 aa/lib/libaa.so: ${wildcard aa/*.o}
7646 bb/lib/libbb.so: ${wildcard bb/*.o}
7647 cc/lib/libcc.so: ${wildcard cc/*.o}
7649 # Make sure all of the shared libraries are in the path before starting the
7652 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7655 ${RM} -rf ${CSC_LIST:%=%/lib}
7656 ${RM} ${CSC_LIST:%=%/*.ali}
7657 ${RM} ${CSC_LIST:%=%/*.o}
7658 ${RM} *.o *.ali ${MAIN}
7661 .. _Automatically_Creating_a_List_of_Directories:
7663 Automatically Creating a List of Directories
7664 --------------------------------------------
7666 In most makefiles, you will have to specify a list of directories, and
7667 store it in a variable. For small projects, it is often easier to
7668 specify each of them by hand, since you then have full control over what
7669 is the proper order for these directories, which ones should be
7672 However, in larger projects, which might involve hundreds of
7673 subdirectories, it might be more convenient to generate this list
7676 The example below presents two methods. The first one, although less
7677 general, gives you more control over the list. It involves wildcard
7678 characters, that are automatically expanded by ``make``. Its
7679 shortcoming is that you need to explicitly specify some of the
7680 organization of your project, such as for instance the directory tree
7681 depth, whether some directories are found in a separate tree, etc.
7683 The second method is the most general one. It requires an external
7684 program, called ``find``, which is standard on all Unix systems. All
7685 the directories found under a given root directory will be added to the
7688 .. code-block:: makefile
7690 # The examples below are based on the following directory hierarchy:
7691 # All the directories can contain any number of files
7692 # ROOT_DIRECTORY -> a -> aa -> aaa
7698 # This Makefile creates a variable called DIRS, that can be reused any time
7699 # you need this list (see the other examples in this section)
7701 # The root of your project's directory hierarchy
7705 # First method: specify explicitly the list of directories
7706 # This allows you to specify any subset of all the directories you need.
7709 DIRS := a/aa/ a/ab/ b/ba/
7712 # Second method: use wildcards
7713 # Note that the argument(s) to wildcard below should end with a '/'.
7714 # Since wildcards also return file names, we have to filter them out
7715 # to avoid duplicate directory names.
7716 # We thus use make's ``dir`` and ``sort`` functions.
7717 # It sets DIRs to the following value (note that the directories aaa and baa
7718 # are not given, unless you change the arguments to wildcard).
7719 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7722 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7723 ${ROOT_DIRECTORY}/*/*/}}}
7726 # Third method: use an external program
7727 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7728 # This is the most complete command: it sets DIRs to the following value:
7729 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7732 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7736 .. _Generating_the_Command_Line_Switches:
7738 Generating the Command Line Switches
7739 ------------------------------------
7741 Once you have created the list of directories as explained in the
7742 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7743 you can easily generate the command line arguments to pass to gnatmake.
7745 For the sake of completeness, this example assumes that the source path
7746 is not the same as the object path, and that you have two separate lists
7749 .. code-block:: makefile
7751 # see "Automatically creating a list of directories" to create
7756 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7757 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7760 gnatmake ${GNATMAKE_SWITCHES} main_unit
7763 .. _Overcoming_Command_Line_Length_Limits:
7765 Overcoming Command Line Length Limits
7766 -------------------------------------
7768 One problem that might be encountered on big projects is that many
7769 operating systems limit the length of the command line. It is thus hard to give
7770 gnatmake the list of source and object directories.
7772 This example shows how you can set up environment variables, which will
7773 make ``gnatmake`` behave exactly as if the directories had been
7774 specified on the command line, but have a much higher length limit (or
7775 even none on most systems).
7777 It assumes that you have created a list of directories in your Makefile,
7778 using one of the methods presented in
7779 :ref:`Automatically_Creating_a_List_of_Directories`.
7780 For the sake of completeness, we assume that the object
7781 path (where the ALI files are found) is different from the sources patch.
7783 Note a small trick in the Makefile below: for efficiency reasons, we
7784 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7785 expanded immediately by ``make``. This way we overcome the standard
7786 make behavior which is to expand the variables only when they are
7789 On Windows, if you are using the standard Windows command shell, you must
7790 replace colons with semicolons in the assignments to these variables.
7792 .. code-block:: makefile
7794 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7795 # This is the same thing as putting the -I arguments on the command line.
7796 # (the equivalent of using -aI on the command line would be to define
7797 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
7798 # You can of course have different values for these variables.
7800 # Note also that we need to keep the previous values of these variables, since
7801 # they might have been set before running 'make' to specify where the GNAT
7802 # library is installed.
7804 # see "Automatically creating a list of directories" to create these
7810 space:=${empty} ${empty}
7811 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
7812 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
7813 ADA_INCLUDE_PATH += ${SOURCE_LIST}
7814 ADA_OBJECTS_PATH += ${OBJECT_LIST}
7815 export ADA_INCLUDE_PATH
7816 export ADA_OBJECTS_PATH