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_Scalar_Alignment`` is the alignment for a scalar whose size is two
1718 machine words. It should be the same as the alignment for C ``long_long`` on
1721 ``Maximum_Alignment`` is the maximum alignment that the compiler might choose
1722 by default for a type or object, which is also the maximum alignment that can
1723 be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT
1724 / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
1725 follows: `Biggest alignment that any data type can require on this machine,
1728 ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
1729 64 for the majority of GCC targets (but can be different on some targets like
1732 ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
1733 documented as follows: `Define this macro to be the value 1 if instructions
1734 will fail to work if given data not on the nominal alignment. If instructions
1735 will merely go slower in that case, define this macro as 0.`
1737 ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
1738 by calls to ``malloc``.
1741 The format of the input file is as follows. First come the values of
1742 the variables defined above, with one line per value:
1749 where ``name`` is the name of the parameter, spelled out in full,
1750 and cased as in the above list, and ``value`` is an unsigned decimal
1751 integer. Two or more blanks separates the name from the value.
1753 All the variables must be present, in alphabetical order (i.e. the
1754 same order as the list above).
1756 Then there is a blank line to separate the two parts of the file. Then
1757 come the lines showing the floating-point types to be registered, with
1758 one line per registered mode:
1763 name digs float_rep size alignment
1766 where ``name`` is the string name of the type (which can have
1767 single spaces embedded in the name (e.g. long double), ``digs`` is
1768 the number of digits for the floating-point type, ``float_rep`` is
1769 the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
1770 AAMP), ``size`` is the size in bits, ``alignment`` is the
1771 alignment in bits. The name is followed by at least two blanks, fields
1772 are separated by at least one blank, and a LF character immediately
1773 follows the alignment field.
1775 Here is an example of a target parameterization file:
1785 Double_Float_Alignment 0
1786 Double_Scalar_Alignment 0
1791 Long_Double_Size 128
1794 Maximum_Alignment 16
1795 Max_Unaligned_Field 64
1799 System_Allocator_Alignment 16
1805 long double 18 I 80 128
1810 .. index:: -gnateu (gcc)
1813 Ignore unrecognized validity, warning, and style switches that
1814 appear after this switch is given. This may be useful when
1815 compiling sources developed on a later version of the compiler
1816 with an earlier version. Of course the earlier version must
1817 support this switch.
1820 .. index:: -gnateV (gcc)
1823 Check that all actual parameters of a subprogram call are valid according to
1824 the rules of validity checking (:ref:`Validity_Checking`).
1827 .. index:: -gnateY (gcc)
1830 Ignore all STYLE_CHECKS pragmas. Full legality checks
1831 are still carried out, but the pragmas have no effect
1832 on what style checks are active. This allows all style
1833 checking options to be controlled from the command line.
1836 .. index:: -gnatE (gcc)
1839 Full dynamic elaboration checks.
1842 .. index:: -gnatf (gcc)
1845 Full errors. Multiple errors per line, all undefined references, do not
1846 attempt to suppress cascaded errors.
1849 .. index:: -gnatF (gcc)
1852 Externals names are folded to all uppercase.
1855 .. index:: -gnatg (gcc)
1858 Internal GNAT implementation mode. This should not be used for applications
1859 programs, it is intended only for use by the compiler and its run-time
1860 library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
1861 implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
1862 warnings and all standard style options are turned on. All warnings and style
1863 messages are treated as errors.
1866 .. index:: -gnatG[nn] (gcc)
1869 List generated expanded code in source form.
1872 .. index:: -gnath (gcc)
1875 Output usage information. The output is written to :file:`stdout`.
1878 .. index:: -gnatH (gcc)
1881 Legacy elaboration-checking mode enabled. When this switch is in effect, the
1882 pre-18.x access-before-elaboration model becomes the de facto model.
1885 .. index:: -gnati (gcc)
1888 Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w).
1889 For details of the possible selections for ``c``,
1890 see :ref:`Character_Set_Control`.
1893 .. index:: -gnatI (gcc)
1896 Ignore representation clauses. When this switch is used,
1897 representation clauses are treated as comments. This is useful
1898 when initially porting code where you want to ignore rep clause
1899 problems, and also for compiling foreign code (particularly
1900 for use with ASIS). The representation clauses that are ignored
1901 are: enumeration_representation_clause, record_representation_clause,
1902 and attribute_definition_clause for the following attributes:
1903 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1904 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
1905 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
1906 Note that this option should be used only for compiling -- the
1907 code is likely to malfunction at run time.
1909 Note that when :switch:`-gnatct` is used to generate trees for input
1910 into ASIS tools, these representation clauses are removed
1911 from the tree and ignored. This means that the tool will not see them.
1914 .. index:: -gnatjnn (gcc)
1916 :switch:`-gnatj{nn}`
1917 Reformat error messages to fit on ``nn`` character lines
1920 .. index:: -gnatJ (gcc)
1923 Permissive elaboration-checking mode enabled. When this switch is in effect,
1924 the post-18.x access-before-elaboration model ignores potential issues with:
1927 - Activations of tasks defined in instances
1929 - Calls from within an instance to its enclosing context
1930 - Calls through generic formal parameters
1931 - Calls to subprograms defined in instances
1933 - Indirect calls using 'Access
1934 - Requeue statements
1936 - Synchronous task suspension
1938 and does not emit compile-time diagnostics or run-time checks.
1941 .. index:: -gnatk (gcc)
1943 :switch:`-gnatk={n}`
1944 Limit file names to ``n`` (1-999) characters (``k`` = krunch).
1947 .. index:: -gnatl (gcc)
1950 Output full source listing with embedded error messages.
1953 .. index:: -gnatL (gcc)
1956 Used in conjunction with -gnatG or -gnatD to intersperse original
1957 source lines (as comment lines with line numbers) in the expanded
1961 .. index:: -gnatm (gcc)
1963 :switch:`-gnatm={n}`
1964 Limit number of detected error or warning messages to ``n``
1965 where ``n`` is in the range 1..999999. The default setting if
1966 no switch is given is 9999. If the number of warnings reaches this
1967 limit, then a message is output and further warnings are suppressed,
1968 but the compilation is continued. If the number of error messages
1969 reaches this limit, then a message is output and the compilation
1970 is abandoned. The equal sign here is optional. A value of zero
1971 means that no limit applies.
1974 .. index:: -gnatn (gcc)
1976 :switch:`-gnatn[12]`
1977 Activate inlining across units for subprograms for which pragma ``Inline``
1978 is specified. This inlining is performed by the GCC back-end. An optional
1979 digit sets the inlining level: 1 for moderate inlining across units
1980 or 2 for full inlining across units. If no inlining level is specified,
1981 the compiler will pick it based on the optimization level.
1984 .. index:: -gnatN (gcc)
1987 Activate front end inlining for subprograms for which
1988 pragma ``Inline`` is specified. This inlining is performed
1989 by the front end and will be visible in the
1990 :switch:`-gnatG` output.
1992 When using a gcc-based back end (in practice this means using any version
1993 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
1994 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
1995 Historically front end inlining was more extensive than the gcc back end
1996 inlining, but that is no longer the case.
1999 .. index:: -gnato0 (gcc)
2002 Suppresses overflow checking. This causes the behavior of the compiler to
2003 match the default for older versions where overflow checking was suppressed
2004 by default. This is equivalent to having
2005 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
2008 .. index:: -gnato?? (gcc)
2011 Set default mode for handling generation of code to avoid intermediate
2012 arithmetic overflow. Here ``??`` is two digits, a
2013 single digit, or nothing. Each digit is one of the digits ``1``
2016 ===== ===============================================================
2017 Digit Interpretation
2018 ----- ---------------------------------------------------------------
2019 *1* All intermediate overflows checked against base type (``STRICT``)
2020 *2* Minimize intermediate overflows (``MINIMIZED``)
2021 *3* Eliminate intermediate overflows (``ELIMINATED``)
2022 ===== ===============================================================
2024 If only one digit appears, then it applies to all
2025 cases; if two digits are given, then the first applies outside
2026 assertions, pre/postconditions, and type invariants, and the second
2027 applies within assertions, pre/postconditions, and type invariants.
2029 If no digits follow the :switch:`-gnato`, then it is equivalent to
2031 causing all intermediate overflows to be handled in strict
2034 This switch also causes arithmetic overflow checking to be performed
2035 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
2037 The default if no option :switch:`-gnato` is given is that overflow handling
2038 is in ``STRICT`` mode (computations done using the base type), and that
2039 overflow checking is enabled.
2041 Note that division by zero is a separate check that is not
2042 controlled by this switch (divide-by-zero checking is on by default).
2044 See also :ref:`Specifying_the_Desired_Mode`.
2047 .. index:: -gnatp (gcc)
2050 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
2051 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
2054 .. index:: -gnat-p (gcc)
2057 Cancel effect of previous :switch:`-gnatp` switch.
2060 .. index:: -gnatP (gcc)
2063 Enable polling. This is required on some systems (notably Windows NT) to
2064 obtain asynchronous abort and asynchronous transfer of control capability.
2065 See ``Pragma_Polling`` in the :title:`GNAT_Reference_Manual` for full
2069 .. index:: -gnatq (gcc)
2072 Don't quit. Try semantics, even if parse errors.
2075 .. index:: -gnatQ (gcc)
2078 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2079 Note that code generation is still suppressed in the presence of any
2080 errors, so even with :switch:`-gnatQ` no object file is generated.
2083 .. index:: -gnatr (gcc)
2086 Treat pragma Restrictions as Restriction_Warnings.
2089 .. index:: -gnatR (gcc)
2091 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
2092 Output representation information for declared types, objects and
2093 subprograms. Note that this switch is not allowed if a previous
2094 :switch:`-gnatD` switch has been given, since these two switches
2098 .. index:: -gnats (gcc)
2104 .. index:: -gnatS (gcc)
2107 Print package Standard.
2110 .. index:: -gnatt (gcc)
2113 Generate tree output file.
2116 .. index:: -gnatT (gcc)
2118 :switch:`-gnatT{nnn}`
2119 All compiler tables start at ``nnn`` times usual starting size.
2122 .. index:: -gnatu (gcc)
2125 List units for this compilation.
2128 .. index:: -gnatU (gcc)
2131 Tag all error messages with the unique string 'error:'
2134 .. index:: -gnatv (gcc)
2137 Verbose mode. Full error output with source lines to :file:`stdout`.
2140 .. index:: -gnatV (gcc)
2143 Control level of validity checking (:ref:`Validity_Checking`).
2146 .. index:: -gnatw (gcc)
2148 :switch:`-gnatw{xxx}`
2150 ``xxx`` is a string of option letters that denotes
2151 the exact warnings that
2152 are enabled or disabled (:ref:`Warning_Message_Control`).
2155 .. index:: -gnatW (gcc)
2158 Wide character encoding method
2159 (``e``\ =n/h/u/s/e/8).
2162 .. index:: -gnatx (gcc)
2165 Suppress generation of cross-reference information.
2168 .. index:: -gnatX (gcc)
2171 Enable GNAT implementation extensions and latest Ada version.
2174 .. index:: -gnaty (gcc)
2177 Enable built-in style checks (:ref:`Style_Checking`).
2180 .. index:: -gnatz (gcc)
2183 Distribution stub generation and compilation
2184 (``m``\ =r/c for receiver/caller stubs).
2192 Direct GNAT to search the ``dir`` directory for source files needed by
2193 the current compilation
2194 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2197 .. index:: -I- (gcc)
2202 Except for the source file named in the command line, do not look for source
2203 files in the directory containing the source file named in the command line
2204 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2210 This switch is used in ``gcc`` to redirect the generated object file
2211 and its associated ALI file. Beware of this switch with GNAT, because it may
2212 cause the object file and ALI file to have different names which in turn
2213 may confuse the binder and the linker.
2216 .. index:: -nostdinc (gcc)
2219 Inhibit the search of the default location for the GNAT Run Time
2220 Library (RTL) source files.
2223 .. index:: -nostdlib (gcc)
2226 Inhibit the search of the default location for the GNAT Run Time
2227 Library (RTL) ALI files.
2233 ``n`` controls the optimization level:
2235 ======= ==================================================================
2237 ------- ------------------------------------------------------------------
2238 *0* No optimization, the default setting if no :switch:`-O` appears
2239 *1* Normal optimization, the default if you specify :switch:`-O` without an
2240 operand. A good compromise between code quality and compilation
2242 *2* Extensive optimization, may improve execution time, possibly at
2243 the cost of substantially increased compilation time.
2244 *3* Same as :switch:`-O2`, and also includes inline expansion for small
2245 subprograms in the same unit.
2246 *s* Optimize space usage
2247 ======= ==================================================================
2249 See also :ref:`Optimization_Levels`.
2252 .. index:: -pass-exit-codes (gcc)
2254 :switch:`-pass-exit-codes`
2255 Catch exit codes from the compiler and use the most meaningful as
2259 .. index:: --RTS (gcc)
2261 :switch:`--RTS={rts-path}`
2262 Specifies the default location of the run-time library. Same meaning as the
2263 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
2269 Used in place of :switch:`-c` to
2270 cause the assembler source file to be
2271 generated, using :file:`.s` as the extension,
2272 instead of the object file.
2273 This may be useful if you need to examine the generated assembly code.
2276 .. index:: -fverbose-asm (gcc)
2278 :switch:`-fverbose-asm`
2279 Used in conjunction with :switch:`-S`
2280 to cause the generated assembly code file to be annotated with variable
2281 names, making it significantly easier to follow.
2287 Show commands generated by the ``gcc`` driver. Normally used only for
2288 debugging purposes or if you need to be sure what version of the
2289 compiler you are executing.
2295 Execute ``ver`` version of the compiler. This is the ``gcc``
2296 version, not the GNAT version.
2302 Turn off warnings generated by the back end of the compiler. Use of
2303 this switch also causes the default for front end warnings to be set
2304 to suppress (as though :switch:`-gnatws` had appeared at the start of
2308 .. index:: Combining GNAT switches
2310 You may combine a sequence of GNAT switches into a single switch. For
2311 example, the combined switch
2317 is equivalent to specifying the following sequence of switches:
2321 -gnato -gnatf -gnati3
2323 The following restrictions apply to the combination of switches
2326 * The switch :switch:`-gnatc` if combined with other switches must come
2327 first in the string.
2329 * The switch :switch:`-gnats` if combined with other switches must come
2330 first in the string.
2333 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
2334 switches, and only one of them may appear in the command line.
2336 * The switch :switch:`-gnat-p` may not be combined with any other switch.
2338 * Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
2339 switch), then all further characters in the switch are interpreted
2340 as style modifiers (see description of :switch:`-gnaty`).
2342 * Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
2343 switch), then all further characters in the switch are interpreted
2344 as debug flags (see description of :switch:`-gnatd`).
2346 * Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
2347 switch), then all further characters in the switch are interpreted
2348 as warning mode modifiers (see description of :switch:`-gnatw`).
2350 * Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
2351 switch), then all further characters in the switch are interpreted
2352 as validity checking options (:ref:`Validity_Checking`).
2354 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2355 a combined list of options.
2357 .. _Output_and_Error_Message_Control:
2359 Output and Error Message Control
2360 --------------------------------
2364 The standard default format for error messages is called 'brief format'.
2365 Brief format messages are written to :file:`stderr` (the standard error
2366 file) and have the following form:
2370 e.adb:3:04: Incorrect spelling of keyword "function"
2371 e.adb:4:20: ";" should be "is"
2373 The first integer after the file name is the line number in the file,
2374 and the second integer is the column number within the line.
2375 ``GPS`` can parse the error messages
2376 and point to the referenced character.
2377 The following switches provide control over the error message
2381 .. index:: -gnatv (gcc)
2384 The ``v`` stands for verbose.
2385 The effect of this setting is to write long-format error
2386 messages to :file:`stdout` (the standard output file.
2387 The same program compiled with the
2388 :switch:`-gnatv` switch would generate:
2392 3. funcion X (Q : Integer)
2394 >>> Incorrect spelling of keyword "function"
2397 >>> ";" should be "is"
2400 The vertical bar indicates the location of the error, and the ``>>>``
2401 prefix can be used to search for error messages. When this switch is
2402 used the only source lines output are those with errors.
2405 .. index:: -gnatl (gcc)
2408 The ``l`` stands for list.
2409 This switch causes a full listing of
2410 the file to be generated. In the case where a body is
2411 compiled, the corresponding spec is also listed, along
2412 with any subunits. Typical output from compiling a package
2413 body :file:`p.adb` might look like::
2417 1. package body p is
2419 3. procedure a is separate;
2430 2. pragma Elaborate_Body
2451 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
2452 standard output is redirected, a brief summary is written to
2453 :file:`stderr` (standard error) giving the number of error messages and
2454 warning messages generated.
2457 .. index:: -gnatl=fname (gcc)
2459 :switch:`-gnatl={fname}`
2460 This has the same effect as :switch:`-gnatl` except that the output is
2461 written to a file instead of to standard output. If the given name
2462 :file:`fname` does not start with a period, then it is the full name
2463 of the file to be written. If :file:`fname` is an extension, it is
2464 appended to the name of the file being compiled. For example, if
2465 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
2466 then the output is written to file xyz.adb.lst.
2469 .. index:: -gnatU (gcc)
2472 This switch forces all error messages to be preceded by the unique
2473 string 'error:'. This means that error messages take a few more
2474 characters in space, but allows easy searching for and identification
2478 .. index:: -gnatb (gcc)
2481 The ``b`` stands for brief.
2482 This switch causes GNAT to generate the
2483 brief format error messages to :file:`stderr` (the standard error
2484 file) as well as the verbose
2485 format message or full listing (which as usual is written to
2486 :file:`stdout` (the standard output file).
2489 .. index:: -gnatm (gcc)
2491 :switch:`-gnatm={n}`
2492 The ``m`` stands for maximum.
2493 ``n`` is a decimal integer in the
2494 range of 1 to 999999 and limits the number of error or warning
2495 messages to be generated. For example, using
2496 :switch:`-gnatm2` might yield
2500 e.adb:3:04: Incorrect spelling of keyword "function"
2501 e.adb:5:35: missing ".."
2502 fatal error: maximum number of errors detected
2503 compilation abandoned
2506 The default setting if
2507 no switch is given is 9999. If the number of warnings reaches this
2508 limit, then a message is output and further warnings are suppressed,
2509 but the compilation is continued. If the number of error messages
2510 reaches this limit, then a message is output and the compilation
2511 is abandoned. A value of zero means that no limit applies.
2513 Note that the equal sign is optional, so the switches
2514 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
2517 .. index:: -gnatf (gcc)
2520 .. index:: Error messages, suppressing
2522 The ``f`` stands for full.
2523 Normally, the compiler suppresses error messages that are likely to be
2524 redundant. This switch causes all error
2525 messages to be generated. In particular, in the case of
2526 references to undefined variables. If a given variable is referenced
2527 several times, the normal format of messages is
2531 e.adb:7:07: "V" is undefined (more references follow)
2533 where the parenthetical comment warns that there are additional
2534 references to the variable ``V``. Compiling the same program with the
2535 :switch:`-gnatf` switch yields
2539 e.adb:7:07: "V" is undefined
2540 e.adb:8:07: "V" is undefined
2541 e.adb:8:12: "V" is undefined
2542 e.adb:8:16: "V" is undefined
2543 e.adb:9:07: "V" is undefined
2544 e.adb:9:12: "V" is undefined
2546 The :switch:`-gnatf` switch also generates additional information for
2547 some error messages. Some examples are:
2549 * Details on possibly non-portable unchecked conversion
2551 * List possible interpretations for ambiguous calls
2553 * Additional details on incorrect parameters
2556 .. index:: -gnatjnn (gcc)
2559 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
2560 with continuation lines are treated as though the continuation lines were
2561 separate messages (and so a warning with two continuation lines counts as
2562 three warnings, and is listed as three separate messages).
2564 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
2565 messages are output in a different manner. A message and all its continuation
2566 lines are treated as a unit, and count as only one warning or message in the
2567 statistics totals. Furthermore, the message is reformatted so that no line
2568 is longer than nn characters.
2571 .. index:: -gnatq (gcc)
2574 The ``q`` stands for quit (really 'don't quit').
2575 In normal operation mode, the compiler first parses the program and
2576 determines if there are any syntax errors. If there are, appropriate
2577 error messages are generated and compilation is immediately terminated.
2579 GNAT to continue with semantic analysis even if syntax errors have been
2580 found. This may enable the detection of more errors in a single run. On
2581 the other hand, the semantic analyzer is more likely to encounter some
2582 internal fatal error when given a syntactically invalid tree.
2585 .. index:: -gnatQ (gcc)
2588 In normal operation mode, the :file:`ALI` file is not generated if any
2589 illegalities are detected in the program. The use of :switch:`-gnatQ` forces
2590 generation of the :file:`ALI` file. This file is marked as being in
2591 error, so it cannot be used for binding purposes, but it does contain
2592 reasonably complete cross-reference information, and thus may be useful
2593 for use by tools (e.g., semantic browsing tools or integrated development
2594 environments) that are driven from the :file:`ALI` file. This switch
2595 implies :switch:`-gnatq`, since the semantic phase must be run to get a
2596 meaningful ALI file.
2598 In addition, if :switch:`-gnatt` is also specified, then the tree file is
2599 generated even if there are illegalities. It may be useful in this case
2600 to also specify :switch:`-gnatq` to ensure that full semantic processing
2601 occurs. The resulting tree file can be processed by ASIS, for the purpose
2602 of providing partial information about illegal units, but if the error
2603 causes the tree to be badly malformed, then ASIS may crash during the
2606 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
2607 being in error, ``gnatmake`` will attempt to recompile the source when it
2608 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
2610 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
2611 since ALI files are never generated if :switch:`-gnats` is set.
2614 .. _Warning_Message_Control:
2616 Warning Message Control
2617 -----------------------
2619 .. index:: Warning messages
2621 In addition to error messages, which correspond to illegalities as defined
2622 in the Ada Reference Manual, the compiler detects two kinds of warning
2625 First, the compiler considers some constructs suspicious and generates a
2626 warning message to alert you to a possible error. Second, if the
2627 compiler detects a situation that is sure to raise an exception at
2628 run time, it generates a warning message. The following shows an example
2629 of warning messages:
2633 e.adb:4:24: warning: creation of object may raise Storage_Error
2634 e.adb:10:17: warning: static value out of range
2635 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2638 GNAT considers a large number of situations as appropriate
2639 for the generation of warning messages. As always, warnings are not
2640 definite indications of errors. For example, if you do an out-of-range
2641 assignment with the deliberate intention of raising a
2642 ``Constraint_Error`` exception, then the warning that may be
2643 issued does not indicate an error. Some of the situations for which GNAT
2644 issues warnings (at least some of the time) are given in the following
2645 list. This list is not complete, and new warnings are often added to
2646 subsequent versions of GNAT. The list is intended to give a general idea
2647 of the kinds of warnings that are generated.
2649 * Possible infinitely recursive calls
2651 * Out-of-range values being assigned
2653 * Possible order of elaboration problems
2655 * Size not a multiple of alignment for a record type
2657 * Assertions (pragma Assert) that are sure to fail
2661 * Address clauses with possibly unaligned values, or where an attempt is
2662 made to overlay a smaller variable with a larger one.
2664 * Fixed-point type declarations with a null range
2666 * Direct_IO or Sequential_IO instantiated with a type that has access values
2668 * Variables that are never assigned a value
2670 * Variables that are referenced before being initialized
2672 * Task entries with no corresponding ``accept`` statement
2674 * Duplicate accepts for the same task entry in a ``select``
2676 * Objects that take too much storage
2678 * Unchecked conversion between types of differing sizes
2680 * Missing ``return`` statement along some execution path in a function
2682 * Incorrect (unrecognized) pragmas
2684 * Incorrect external names
2686 * Allocation from empty storage pool
2688 * Potentially blocking operation in protected type
2690 * Suspicious parenthesization of expressions
2692 * Mismatching bounds in an aggregate
2694 * Attempt to return local value by reference
2696 * Premature instantiation of a generic body
2698 * Attempt to pack aliased components
2700 * Out of bounds array subscripts
2702 * Wrong length on string assignment
2704 * Violations of style rules if style checking is enabled
2706 * Unused |with| clauses
2708 * ``Bit_Order`` usage that does not have any effect
2710 * ``Standard.Duration`` used to resolve universal fixed expression
2712 * Dereference of possibly null value
2714 * Declaration that is likely to cause storage error
2716 * Internal GNAT unit |withed| by application unit
2718 * Values known to be out of range at compile time
2720 * Unreferenced or unmodified variables. Note that a special
2721 exemption applies to variables which contain any of the substrings
2722 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
2723 are considered likely to be intentionally used in a situation where
2724 otherwise a warning would be given, so warnings of this kind are
2725 always suppressed for such variables.
2727 * Address overlays that could clobber memory
2729 * Unexpected initialization when address clause present
2731 * Bad alignment for address clause
2733 * Useless type conversions
2735 * Redundant assignment statements and other redundant constructs
2737 * Useless exception handlers
2739 * Accidental hiding of name by child unit
2741 * Access before elaboration detected at compile time
2743 * A range in a ``for`` loop that is known to be null or might be null
2746 The following section lists compiler switches that are available
2747 to control the handling of warning messages. It is also possible
2748 to exercise much finer control over what warnings are issued and
2749 suppressed using the GNAT pragma Warnings (see the description
2750 of the pragma in the :title:`GNAT_Reference_manual`).
2753 .. index:: -gnatwa (gcc)
2756 *Activate most optional warnings.*
2758 This switch activates most optional warning messages. See the remaining list
2759 in this section for details on optional warning messages that can be
2760 individually controlled. The warnings that are not turned on by this
2764 * :switch:`-gnatwd` (implicit dereferencing)
2766 * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
2768 * :switch:`-gnatwh` (hiding)
2770 * :switch:`-gnatw.h` (holes in record layouts)
2772 * :switch:`-gnatw.j` (late primitives of tagged types)
2774 * :switch:`-gnatw.k` (redefinition of names in standard)
2776 * :switch:`-gnatwl` (elaboration warnings)
2778 * :switch:`-gnatw.l` (inherited aspects)
2780 * :switch:`-gnatw.n` (atomic synchronization)
2782 * :switch:`-gnatwo` (address clause overlay)
2784 * :switch:`-gnatw.o` (values set by out parameters ignored)
2786 * :switch:`-gnatw.q` (questionable layout of record types)
2788 * :switch:`-gnatw.s` (overridden size clause)
2790 * :switch:`-gnatwt` (tracking of deleted conditional code)
2792 * :switch:`-gnatw.u` (unordered enumeration)
2794 * :switch:`-gnatw.w` (use of Warnings Off)
2796 * :switch:`-gnatw.y` (reasons for package needing body)
2798 All other optional warnings are turned on.
2801 .. index:: -gnatwA (gcc)
2804 *Suppress all optional errors.*
2806 This switch suppresses all optional warning messages, see remaining list
2807 in this section for details on optional warning messages that can be
2808 individually controlled. Note that unlike switch :switch:`-gnatws`, the
2809 use of switch :switch:`-gnatwA` does not suppress warnings that are
2810 normally given unconditionally and cannot be individually controlled
2811 (for example, the warning about a missing exit path in a function).
2812 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
2813 the use of switch :switch:`-gnatwA` can be individually turned back
2814 on. For example the use of switch :switch:`-gnatwA` followed by
2815 switch :switch:`-gnatwd` will suppress all optional warnings except
2816 the warnings for implicit dereferencing.
2818 .. index:: -gnatw.a (gcc)
2821 *Activate warnings on failing assertions.*
2823 .. index:: Assert failures
2825 This switch activates warnings for assertions where the compiler can tell at
2826 compile time that the assertion will fail. Note that this warning is given
2827 even if assertions are disabled. The default is that such warnings are
2831 .. index:: -gnatw.A (gcc)
2834 *Suppress warnings on failing assertions.*
2836 .. index:: Assert failures
2838 This switch suppresses warnings for assertions where the compiler can tell at
2839 compile time that the assertion will fail.
2842 .. index:: -gnatwb (gcc)
2845 *Activate warnings on bad fixed values.*
2847 .. index:: Bad fixed values
2849 .. index:: Fixed-point Small value
2851 .. index:: Small value
2853 This switch activates warnings for static fixed-point expressions whose
2854 value is not an exact multiple of Small. Such values are implementation
2855 dependent, since an implementation is free to choose either of the multiples
2856 that surround the value. GNAT always chooses the closer one, but this is not
2857 required behavior, and it is better to specify a value that is an exact
2858 multiple, ensuring predictable execution. The default is that such warnings
2862 .. index:: -gnatwB (gcc)
2865 *Suppress warnings on bad fixed values.*
2867 This switch suppresses warnings for static fixed-point expressions whose
2868 value is not an exact multiple of Small.
2871 .. index:: -gnatw.b (gcc)
2874 *Activate warnings on biased representation.*
2876 .. index:: Biased representation
2878 This switch activates warnings when a size clause, value size clause, component
2879 clause, or component size clause forces the use of biased representation for an
2880 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2881 to represent 10/11). The default is that such warnings are generated.
2884 .. index:: -gnatwB (gcc)
2887 *Suppress warnings on biased representation.*
2889 This switch suppresses warnings for representation clauses that force the use
2890 of biased representation.
2893 .. index:: -gnatwc (gcc)
2896 *Activate warnings on conditionals.*
2898 .. index:: Conditionals, constant
2900 This switch activates warnings for conditional expressions used in
2901 tests that are known to be True or False at compile time. The default
2902 is that such warnings are not generated.
2903 Note that this warning does
2904 not get issued for the use of boolean variables or constants whose
2905 values are known at compile time, since this is a standard technique
2906 for conditional compilation in Ada, and this would generate too many
2907 false positive warnings.
2909 This warning option also activates a special test for comparisons using
2910 the operators '>=' and' <='.
2911 If the compiler can tell that only the equality condition is possible,
2912 then it will warn that the '>' or '<' part of the test
2913 is useless and that the operator could be replaced by '='.
2914 An example would be comparing a ``Natural`` variable <= 0.
2916 This warning option also generates warnings if
2917 one or both tests is optimized away in a membership test for integer
2918 values if the result can be determined at compile time. Range tests on
2919 enumeration types are not included, since it is common for such tests
2920 to include an end point.
2922 This warning can also be turned on using :switch:`-gnatwa`.
2925 .. index:: -gnatwC (gcc)
2928 *Suppress warnings on conditionals.*
2930 This switch suppresses warnings for conditional expressions used in
2931 tests that are known to be True or False at compile time.
2934 .. index:: -gnatw.c (gcc)
2937 *Activate warnings on missing component clauses.*
2939 .. index:: Component clause, missing
2941 This switch activates warnings for record components where a record
2942 representation clause is present and has component clauses for the
2943 majority, but not all, of the components. A warning is given for each
2944 component for which no component clause is present.
2947 .. index:: -gnatwC (gcc)
2950 *Suppress warnings on missing component clauses.*
2952 This switch suppresses warnings for record components that are
2953 missing a component clause in the situation described above.
2956 .. index:: -gnatwd (gcc)
2959 *Activate warnings on implicit dereferencing.*
2961 If this switch is set, then the use of a prefix of an access type
2962 in an indexed component, slice, or selected component without an
2963 explicit ``.all`` will generate a warning. With this warning
2964 enabled, access checks occur only at points where an explicit
2965 ``.all`` appears in the source code (assuming no warnings are
2966 generated as a result of this switch). The default is that such
2967 warnings are not generated.
2970 .. index:: -gnatwD (gcc)
2973 *Suppress warnings on implicit dereferencing.*
2975 .. index:: Implicit dereferencing
2977 .. index:: Dereferencing, implicit
2979 This switch suppresses warnings for implicit dereferences in
2980 indexed components, slices, and selected components.
2983 .. index:: -gnatw.d (gcc)
2986 *Activate tagging of warning and info messages.*
2988 If this switch is set, then warning messages are tagged, with one of the
2992 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
2997 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
3002 Used to tag elaboration information (info) messages generated when the
3003 static model of elaboration is used and the :switch:`-gnatel` switch is set.
3006 - *[restriction warning]*
3007 Used to tag warning messages for restriction violations, activated by use
3008 of the pragma ``Restriction_Warnings``.
3011 - *[warning-as-error]*
3012 Used to tag warning messages that have been converted to error messages by
3013 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
3014 the string "error: " rather than "warning: ".
3017 - *[enabled by default]*
3018 Used to tag all other warnings that are always given by default, unless
3019 warnings are completely suppressed using pragma *Warnings(Off)* or
3020 the switch :switch:`-gnatws`.
3024 .. index:: -gnatw.d (gcc)
3027 *Deactivate tagging of warning and info messages messages.*
3029 If this switch is set, then warning messages return to the default
3030 mode in which warnings and info messages are not tagged as described above for
3034 .. index:: -gnatwe (gcc)
3035 .. index:: Warnings, treat as error
3038 *Treat warnings and style checks as errors.*
3040 This switch causes warning messages and style check messages to be
3042 The warning string still appears, but the warning messages are counted
3043 as errors, and prevent the generation of an object file. Note that this
3044 is the only -gnatw switch that affects the handling of style check messages.
3045 Note also that this switch has no effect on info (information) messages, which
3046 are not treated as errors if this switch is present.
3049 .. index:: -gnatw.e (gcc)
3052 *Activate every optional warning.*
3054 .. index:: Warnings, activate every optional warning
3056 This switch activates all optional warnings, including those which
3057 are not activated by :switch:`-gnatwa`. The use of this switch is not
3058 recommended for normal use. If you turn this switch on, it is almost
3059 certain that you will get large numbers of useless warnings. The
3060 warnings that are excluded from :switch:`-gnatwa` are typically highly
3061 specialized warnings that are suitable for use only in code that has
3062 been specifically designed according to specialized coding rules.
3065 .. index:: -gnatwE (gcc)
3066 .. index:: Warnings, treat as error
3069 *Treat all run-time exception warnings as errors.*
3071 This switch causes warning messages regarding errors that will be raised
3072 during run-time execution to be treated as errors.
3075 .. index:: -gnatwf (gcc)
3078 *Activate warnings on unreferenced formals.*
3080 .. index:: Formals, unreferenced
3082 This switch causes a warning to be generated if a formal parameter
3083 is not referenced in the body of the subprogram. This warning can
3084 also be turned on using :switch:`-gnatwu`. The
3085 default is that these warnings are not generated.
3088 .. index:: -gnatwF (gcc)
3091 *Suppress warnings on unreferenced formals.*
3093 This switch suppresses warnings for unreferenced formal
3094 parameters. Note that the
3095 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
3096 effect of warning on unreferenced entities other than subprogram
3100 .. index:: -gnatwg (gcc)
3103 *Activate warnings on unrecognized pragmas.*
3105 .. index:: Pragmas, unrecognized
3107 This switch causes a warning to be generated if an unrecognized
3108 pragma is encountered. Apart from issuing this warning, the
3109 pragma is ignored and has no effect. The default
3110 is that such warnings are issued (satisfying the Ada Reference
3111 Manual requirement that such warnings appear).
3114 .. index:: -gnatwG (gcc)
3117 *Suppress warnings on unrecognized pragmas.*
3119 This switch suppresses warnings for unrecognized pragmas.
3122 .. index:: -gnatw.g (gcc)
3125 *Warnings used for GNAT sources.*
3127 This switch sets the warning categories that are used by the standard
3128 GNAT style. Currently this is equivalent to
3129 :switch:`-gnatwAao.q.s.CI.V.X.Z`
3130 but more warnings may be added in the future without advanced notice.
3133 .. index:: -gnatwh (gcc)
3136 *Activate warnings on hiding.*
3138 .. index:: Hiding of Declarations
3140 This switch activates warnings on hiding declarations that are considered
3141 potentially confusing. Not all cases of hiding cause warnings; for example an
3142 overriding declaration hides an implicit declaration, which is just normal
3143 code. The default is that warnings on hiding are not generated.
3146 .. index:: -gnatwH (gcc)
3149 *Suppress warnings on hiding.*
3151 This switch suppresses warnings on hiding declarations.
3154 .. index:: -gnatw.h (gcc)
3157 *Activate warnings on holes/gaps in records.*
3159 .. index:: Record Representation (gaps)
3161 This switch activates warnings on component clauses in record
3162 representation clauses that leave holes (gaps) in the record layout.
3163 If this warning option is active, then record representation clauses
3164 should specify a contiguous layout, adding unused fill fields if needed.
3167 .. index:: -gnatw.H (gcc)
3170 *Suppress warnings on holes/gaps in records.*
3172 This switch suppresses warnings on component clauses in record
3173 representation clauses that leave holes (haps) in the record layout.
3176 .. index:: -gnatwi (gcc)
3179 *Activate warnings on implementation units.*
3181 This switch activates warnings for a |with| of an internal GNAT
3182 implementation unit, defined as any unit from the ``Ada``,
3183 ``Interfaces``, ``GNAT``,
3185 hierarchies that is not
3186 documented in either the Ada Reference Manual or the GNAT
3187 Programmer's Reference Manual. Such units are intended only
3188 for internal implementation purposes and should not be |withed|
3189 by user programs. The default is that such warnings are generated
3192 .. index:: -gnatwI (gcc)
3195 *Disable warnings on implementation units.*
3197 This switch disables warnings for a |with| of an internal GNAT
3198 implementation unit.
3201 .. index:: -gnatw.i (gcc)
3204 *Activate warnings on overlapping actuals.*
3206 This switch enables a warning on statically detectable overlapping actuals in
3207 a subprogram call, when one of the actuals is an in-out parameter, and the
3208 types of the actuals are not by-copy types. This warning is off by default.
3211 .. index:: -gnatw.I (gcc)
3214 *Disable warnings on overlapping actuals.*
3216 This switch disables warnings on overlapping actuals in a call..
3219 .. index:: -gnatwj (gcc)
3222 *Activate warnings on obsolescent features (Annex J).*
3224 .. index:: Features, obsolescent
3226 .. index:: Obsolescent features
3228 If this warning option is activated, then warnings are generated for
3229 calls to subprograms marked with ``pragma Obsolescent`` and
3230 for use of features in Annex J of the Ada Reference Manual. In the
3231 case of Annex J, not all features are flagged. In particular use
3232 of the renamed packages (like ``Text_IO``) and use of package
3233 ``ASCII`` are not flagged, since these are very common and
3234 would generate many annoying positive warnings. The default is that
3235 such warnings are not generated.
3237 In addition to the above cases, warnings are also generated for
3238 GNAT features that have been provided in past versions but which
3239 have been superseded (typically by features in the new Ada standard).
3240 For example, ``pragma Ravenscar`` will be flagged since its
3241 function is replaced by ``pragma Profile(Ravenscar)``, and
3242 ``pragma Interface_Name`` will be flagged since its function
3243 is replaced by ``pragma Import``.
3245 Note that this warning option functions differently from the
3246 restriction ``No_Obsolescent_Features`` in two respects.
3247 First, the restriction applies only to annex J features.
3248 Second, the restriction does flag uses of package ``ASCII``.
3251 .. index:: -gnatwJ (gcc)
3254 *Suppress warnings on obsolescent features (Annex J).*
3256 This switch disables warnings on use of obsolescent features.
3259 .. index:: -gnatw.j (gcc)
3262 *Activate warnings on late declarations of tagged type primitives.*
3264 This switch activates warnings on visible primitives added to a
3265 tagged type after deriving a private extension from it.
3268 .. index:: -gnatw.J (gcc)
3271 *Suppress warnings on late declarations of tagged type primitives.*
3273 This switch suppresses warnings on visible primitives added to a
3274 tagged type after deriving a private extension from it.
3277 .. index:: -gnatwk (gcc)
3280 *Activate warnings on variables that could be constants.*
3282 This switch activates warnings for variables that are initialized but
3283 never modified, and then could be declared constants. The default is that
3284 such warnings are not given.
3287 .. index:: -gnatwK (gcc)
3290 *Suppress warnings on variables that could be constants.*
3292 This switch disables warnings on variables that could be declared constants.
3295 .. index:: -gnatw.k (gcc)
3298 *Activate warnings on redefinition of names in standard.*
3300 This switch activates warnings for declarations that declare a name that
3301 is defined in package Standard. Such declarations can be confusing,
3302 especially since the names in package Standard continue to be directly
3303 visible, meaning that use visibiliy on such redeclared names does not
3304 work as expected. Names of discriminants and components in records are
3305 not included in this check.
3308 .. index:: -gnatwK (gcc)
3311 *Suppress warnings on redefinition of names in standard.*
3313 This switch activates warnings for declarations that declare a name that
3314 is defined in package Standard.
3317 .. index:: -gnatwl (gcc)
3320 *Activate warnings for elaboration pragmas.*
3322 .. index:: Elaboration, warnings
3324 This switch activates warnings for possible elaboration problems,
3325 including suspicious use
3326 of ``Elaborate`` pragmas, when using the static elaboration model, and
3327 possible situations that may raise ``Program_Error`` when using the
3328 dynamic elaboration model.
3329 See the section in this guide on elaboration checking for further details.
3330 The default is that such warnings
3334 .. index:: -gnatwL (gcc)
3337 *Suppress warnings for elaboration pragmas.*
3339 This switch suppresses warnings for possible elaboration problems.
3342 .. index:: -gnatw.l (gcc)
3345 *List inherited aspects.*
3347 This switch causes the compiler to list inherited invariants,
3348 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3349 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3352 .. index:: -gnatw.L (gcc)
3355 *Suppress listing of inherited aspects.*
3357 This switch suppresses listing of inherited aspects.
3360 .. index:: -gnatwm (gcc)
3363 *Activate warnings on modified but unreferenced variables.*
3365 This switch activates warnings for variables that are assigned (using
3366 an initialization value or with one or more assignment statements) but
3367 whose value is never read. The warning is suppressed for volatile
3368 variables and also for variables that are renamings of other variables
3369 or for which an address clause is given.
3370 The default is that these warnings are not given.
3373 .. index:: -gnatwM (gcc)
3376 *Disable warnings on modified but unreferenced variables.*
3378 This switch disables warnings for variables that are assigned or
3379 initialized, but never read.
3382 .. index:: -gnatw.m (gcc)
3385 *Activate warnings on suspicious modulus values.*
3387 This switch activates warnings for modulus values that seem suspicious.
3388 The cases caught are where the size is the same as the modulus (e.g.
3389 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3390 with no size clause. The guess in both cases is that 2**x was intended
3391 rather than x. In addition expressions of the form 2*x for small x
3392 generate a warning (the almost certainly accurate guess being that
3393 2**x was intended). The default is that these warnings are given.
3396 .. index:: -gnatw.M (gcc)
3399 *Disable warnings on suspicious modulus values.*
3401 This switch disables warnings for suspicious modulus values.
3404 .. index:: -gnatwn (gcc)
3407 *Set normal warnings mode.*
3409 This switch sets normal warning mode, in which enabled warnings are
3410 issued and treated as warnings rather than errors. This is the default
3411 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
3412 an explicit :switch:`-gnatws` or
3413 :switch:`-gnatwe`. It also cancels the effect of the
3414 implicit :switch:`-gnatwe` that is activated by the
3415 use of :switch:`-gnatg`.
3418 .. index:: -gnatw.n (gcc)
3419 .. index:: Atomic Synchronization, warnings
3422 *Activate warnings on atomic synchronization.*
3424 This switch actives warnings when an access to an atomic variable
3425 requires the generation of atomic synchronization code. These
3426 warnings are off by default.
3428 .. index:: -gnatw.N (gcc)
3431 *Suppress warnings on atomic synchronization.*
3433 .. index:: Atomic Synchronization, warnings
3435 This switch suppresses warnings when an access to an atomic variable
3436 requires the generation of atomic synchronization code.
3439 .. index:: -gnatwo (gcc)
3440 .. index:: Address Clauses, warnings
3443 *Activate warnings on address clause overlays.*
3445 This switch activates warnings for possibly unintended initialization
3446 effects of defining address clauses that cause one variable to overlap
3447 another. The default is that such warnings are generated.
3450 .. index:: -gnatwO (gcc)
3453 *Suppress warnings on address clause overlays.*
3455 This switch suppresses warnings on possibly unintended initialization
3456 effects of defining address clauses that cause one variable to overlap
3460 .. index:: -gnatw.o (gcc)
3463 *Activate warnings on modified but unreferenced out parameters.*
3465 This switch activates warnings for variables that are modified by using
3466 them as actuals for a call to a procedure with an out mode formal, where
3467 the resulting assigned value is never read. It is applicable in the case
3468 where there is more than one out mode formal. If there is only one out
3469 mode formal, the warning is issued by default (controlled by -gnatwu).
3470 The warning is suppressed for volatile
3471 variables and also for variables that are renamings of other variables
3472 or for which an address clause is given.
3473 The default is that these warnings are not given.
3476 .. index:: -gnatw.O (gcc)
3479 *Disable warnings on modified but unreferenced out parameters.*
3481 This switch suppresses warnings for variables that are modified by using
3482 them as actuals for a call to a procedure with an out mode formal, where
3483 the resulting assigned value is never read.
3486 .. index:: -gnatwp (gcc)
3487 .. index:: Inlining, warnings
3490 *Activate warnings on ineffective pragma Inlines.*
3492 This switch activates warnings for failure of front end inlining
3493 (activated by :switch:`-gnatN`) to inline a particular call. There are
3494 many reasons for not being able to inline a call, including most
3495 commonly that the call is too complex to inline. The default is
3496 that such warnings are not given.
3497 Warnings on ineffective inlining by the gcc back-end can be activated
3498 separately, using the gcc switch -Winline.
3501 .. index:: -gnatwP (gcc)
3504 *Suppress warnings on ineffective pragma Inlines.*
3506 This switch suppresses warnings on ineffective pragma Inlines. If the
3507 inlining mechanism cannot inline a call, it will simply ignore the
3511 .. index:: -gnatw.p (gcc)
3512 .. index:: Parameter order, warnings
3515 *Activate warnings on parameter ordering.*
3517 This switch activates warnings for cases of suspicious parameter
3518 ordering when the list of arguments are all simple identifiers that
3519 match the names of the formals, but are in a different order. The
3520 warning is suppressed if any use of named parameter notation is used,
3521 so this is the appropriate way to suppress a false positive (and
3522 serves to emphasize that the "misordering" is deliberate). The
3523 default is that such warnings are not given.
3526 .. index:: -gnatw.P (gcc)
3529 *Suppress warnings on parameter ordering.*
3531 This switch suppresses warnings on cases of suspicious parameter
3535 .. index:: -gnatwq (gcc)
3536 .. index:: Parentheses, warnings
3539 *Activate warnings on questionable missing parentheses.*
3541 This switch activates warnings for cases where parentheses are not used and
3542 the result is potential ambiguity from a readers point of view. For example
3543 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3544 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3545 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3546 follow the rule of always parenthesizing to make the association clear, and
3547 this warning switch warns if such parentheses are not present. The default
3548 is that these warnings are given.
3551 .. index:: -gnatwQ (gcc)
3554 *Suppress warnings on questionable missing parentheses.*
3556 This switch suppresses warnings for cases where the association is not
3557 clear and the use of parentheses is preferred.
3560 .. index:: -gnatw.q (gcc)
3561 .. index:: Layout, warnings
3564 *Activate warnings on questionable layout of record types.*
3566 This switch activates warnings for cases where the default layout of
3567 a record type, that is to say the layout of its components in textual
3568 order of the source code, would very likely cause inefficiencies in
3569 the code generated by the compiler, both in terms of space and speed
3570 during execution. One warning is issued for each problematic component
3571 without representation clause in the nonvariant part and then in each
3572 variant recursively, if any.
3574 The purpose of these warnings is neither to prescribe an optimal layout
3575 nor to force the use of representation clauses, but rather to get rid of
3576 the most blatant inefficiencies in the layout. Therefore, the default
3577 layout is matched against the following synthetic ordered layout and
3578 the deviations are flagged on a component-by-component basis:
3580 * first all components or groups of components whose length is fixed
3581 and a multiple of the storage unit,
3583 * then the remaining components whose length is fixed and not a multiple
3584 of the storage unit,
3586 * then the remaining components whose length doesn't depend on discriminants
3587 (that is to say, with variable but uniform length for all objects),
3589 * then all components whose length depends on discriminants,
3591 * finally the variant part (if any),
3593 for the nonvariant part and for each variant recursively, if any.
3595 The exact wording of the warning depends on whether the compiler is allowed
3596 to reorder the components in the record type or precluded from doing it by
3597 means of pragma ``No_Component_Reordering``.
3599 The default is that these warnings are not given.
3601 .. index:: -gnatw.Q (gcc)
3604 *Suppress warnings on questionable layout of record types.*
3606 This switch suppresses warnings for cases where the default layout of
3607 a record type would very likely cause inefficiencies.
3610 .. index:: -gnatwr (gcc)
3613 *Activate warnings on redundant constructs.*
3615 This switch activates warnings for redundant constructs. The following
3616 is the current list of constructs regarded as redundant:
3618 * Assignment of an item to itself.
3620 * Type conversion that converts an expression to its own type.
3622 * Use of the attribute ``Base`` where ``typ'Base`` is the same
3625 * Use of pragma ``Pack`` when all components are placed by a record
3626 representation clause.
3628 * Exception handler containing only a reraise statement (raise with no
3629 operand) which has no effect.
3631 * Use of the operator abs on an operand that is known at compile time
3634 * Comparison of an object or (unary or binary) operation of boolean type to
3635 an explicit True value.
3637 The default is that warnings for redundant constructs are not given.
3640 .. index:: -gnatwR (gcc)
3643 *Suppress warnings on redundant constructs.*
3645 This switch suppresses warnings for redundant constructs.
3648 .. index:: -gnatw.r (gcc)
3651 *Activate warnings for object renaming function.*
3653 This switch activates warnings for an object renaming that renames a
3654 function call, which is equivalent to a constant declaration (as
3655 opposed to renaming the function itself). The default is that these
3659 .. index:: -gnatwT (gcc)
3662 *Suppress warnings for object renaming function.*
3664 This switch suppresses warnings for object renaming function.
3667 .. index:: -gnatws (gcc)
3670 *Suppress all warnings.*
3672 This switch completely suppresses the
3673 output of all warning messages from the GNAT front end, including
3674 both warnings that can be controlled by switches described in this
3675 section, and those that are normally given unconditionally. The
3676 effect of this suppress action can only be cancelled by a subsequent
3677 use of the switch :switch:`-gnatwn`.
3679 Note that switch :switch:`-gnatws` does not suppress
3680 warnings from the ``gcc`` back end.
3681 To suppress these back end warnings as well, use the switch :switch:`-w`
3682 in addition to :switch:`-gnatws`. Also this switch has no effect on the
3683 handling of style check messages.
3686 .. index:: -gnatw.s (gcc)
3687 .. index:: Record Representation (component sizes)
3690 *Activate warnings on overridden size clauses.*
3692 This switch activates warnings on component clauses in record
3693 representation clauses where the length given overrides that
3694 specified by an explicit size clause for the component type. A
3695 warning is similarly given in the array case if a specified
3696 component size overrides an explicit size clause for the array
3700 .. index:: -gnatw.S (gcc)
3703 *Suppress warnings on overridden size clauses.*
3705 This switch suppresses warnings on component clauses in record
3706 representation clauses that override size clauses, and similar
3707 warnings when an array component size overrides a size clause.
3710 .. index:: -gnatwt (gcc)
3711 .. index:: Deactivated code, warnings
3712 .. index:: Deleted code, warnings
3715 *Activate warnings for tracking of deleted conditional code.*
3717 This switch activates warnings for tracking of code in conditionals (IF and
3718 CASE statements) that is detected to be dead code which cannot be executed, and
3719 which is removed by the front end. This warning is off by default. This may be
3720 useful for detecting deactivated code in certified applications.
3723 .. index:: -gnatwT (gcc)
3726 *Suppress warnings for tracking of deleted conditional code.*
3728 This switch suppresses warnings for tracking of deleted conditional code.
3731 .. index:: -gnatw.t (gcc)
3734 *Activate warnings on suspicious contracts.*
3736 This switch activates warnings on suspicious contracts. This includes
3737 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
3738 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3739 ``Contract_Cases``). A function postcondition or contract case is suspicious
3740 when no postcondition or contract case for this function mentions the result
3741 of the function. A procedure postcondition or contract case is suspicious
3742 when it only refers to the pre-state of the procedure, because in that case
3743 it should rather be expressed as a precondition. This switch also controls
3744 warnings on suspicious cases of expressions typically found in contracts like
3745 quantified expressions and uses of Update attribute. The default is that such
3746 warnings are generated.
3749 .. index:: -gnatw.T (gcc)
3752 *Suppress warnings on suspicious contracts.*
3754 This switch suppresses warnings on suspicious contracts.
3757 .. index:: -gnatwu (gcc)
3760 *Activate warnings on unused entities.*
3762 This switch activates warnings to be generated for entities that
3763 are declared but not referenced, and for units that are |withed|
3765 referenced. In the case of packages, a warning is also generated if
3766 no entities in the package are referenced. This means that if a with'ed
3767 package is referenced but the only references are in ``use``
3768 clauses or ``renames``
3769 declarations, a warning is still generated. A warning is also generated
3770 for a generic package that is |withed| but never instantiated.
3771 In the case where a package or subprogram body is compiled, and there
3772 is a |with| on the corresponding spec
3773 that is only referenced in the body,
3774 a warning is also generated, noting that the
3775 |with| can be moved to the body. The default is that
3776 such warnings are not generated.
3777 This switch also activates warnings on unreferenced formals
3778 (it includes the effect of :switch:`-gnatwf`).
3781 .. index:: -gnatwU (gcc)
3784 *Suppress warnings on unused entities.*
3786 This switch suppresses warnings for unused entities and packages.
3787 It also turns off warnings on unreferenced formals (and thus includes
3788 the effect of :switch:`-gnatwF`).
3791 .. index:: -gnatw.u (gcc)
3794 *Activate warnings on unordered enumeration types.*
3796 This switch causes enumeration types to be considered as conceptually
3797 unordered, unless an explicit pragma ``Ordered`` is given for the type.
3798 The effect is to generate warnings in clients that use explicit comparisons
3799 or subranges, since these constructs both treat objects of the type as
3800 ordered. (A *client* is defined as a unit that is other than the unit in
3801 which the type is declared, or its body or subunits.) Please refer to
3802 the description of pragma ``Ordered`` in the
3803 :title:`GNAT Reference Manual` for further details.
3804 The default is that such warnings are not generated.
3807 .. index:: -gnatw.U (gcc)
3810 *Deactivate warnings on unordered enumeration types.*
3812 This switch causes all enumeration types to be considered as ordered, so
3813 that no warnings are given for comparisons or subranges for any type.
3816 .. index:: -gnatwv (gcc)
3817 .. index:: Unassigned variable warnings
3820 *Activate warnings on unassigned variables.*
3822 This switch activates warnings for access to variables which
3823 may not be properly initialized. The default is that
3824 such warnings are generated.
3827 .. index:: -gnatwV (gcc)
3830 *Suppress warnings on unassigned variables.*
3832 This switch suppresses warnings for access to variables which
3833 may not be properly initialized.
3834 For variables of a composite type, the warning can also be suppressed in
3835 Ada 2005 by using a default initialization with a box. For example, if
3836 Table is an array of records whose components are only partially uninitialized,
3837 then the following code:
3841 Tab : Table := (others => <>);
3843 will suppress warnings on subsequent statements that access components
3847 .. index:: -gnatw.v (gcc)
3848 .. index:: bit order warnings
3851 *Activate info messages for non-default bit order.*
3853 This switch activates messages (labeled "info", they are not warnings,
3854 just informational messages) about the effects of non-default bit-order
3855 on records to which a component clause is applied. The effect of specifying
3856 non-default bit ordering is a bit subtle (and changed with Ada 2005), so
3857 these messages, which are given by default, are useful in understanding the
3858 exact consequences of using this feature.
3861 .. index:: -gnatw.V (gcc)
3864 *Suppress info messages for non-default bit order.*
3866 This switch suppresses information messages for the effects of specifying
3867 non-default bit order on record components with component clauses.
3870 .. index:: -gnatww (gcc)
3871 .. index:: String indexing warnings
3874 *Activate warnings on wrong low bound assumption.*
3876 This switch activates warnings for indexing an unconstrained string parameter
3877 with a literal or S'Length. This is a case where the code is assuming that the
3878 low bound is one, which is in general not true (for example when a slice is
3879 passed). The default is that such warnings are generated.
3882 .. index:: -gnatwW (gcc)
3885 *Suppress warnings on wrong low bound assumption.*
3887 This switch suppresses warnings for indexing an unconstrained string parameter
3888 with a literal or S'Length. Note that this warning can also be suppressed
3889 in a particular case by adding an assertion that the lower bound is 1,
3890 as shown in the following example:
3894 procedure K (S : String) is
3895 pragma Assert (S'First = 1);
3899 .. index:: -gnatw.w (gcc)
3900 .. index:: Warnings Off control
3903 *Activate warnings on Warnings Off pragmas.*
3905 This switch activates warnings for use of ``pragma Warnings (Off, entity)``
3906 where either the pragma is entirely useless (because it suppresses no
3907 warnings), or it could be replaced by ``pragma Unreferenced`` or
3908 ``pragma Unmodified``.
3909 Also activates warnings for the case of
3910 Warnings (Off, String), where either there is no matching
3911 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
3912 The default is that these warnings are not given.
3915 .. index:: -gnatw.W (gcc)
3918 *Suppress warnings on unnecessary Warnings Off pragmas.*
3920 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
3923 .. index:: -gnatwx (gcc)
3924 .. index:: Export/Import pragma warnings
3927 *Activate warnings on Export/Import pragmas.*
3929 This switch activates warnings on Export/Import pragmas when
3930 the compiler detects a possible conflict between the Ada and
3931 foreign language calling sequences. For example, the use of
3932 default parameters in a convention C procedure is dubious
3933 because the C compiler cannot supply the proper default, so
3934 a warning is issued. The default is that such warnings are
3938 .. index:: -gnatwX (gcc)
3941 *Suppress warnings on Export/Import pragmas.*
3943 This switch suppresses warnings on Export/Import pragmas.
3944 The sense of this is that you are telling the compiler that
3945 you know what you are doing in writing the pragma, and it
3946 should not complain at you.
3949 .. index:: -gnatwm (gcc)
3952 *Activate warnings for No_Exception_Propagation mode.*
3954 This switch activates warnings for exception usage when pragma Restrictions
3955 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
3956 explicit exception raises which are not covered by a local handler, and for
3957 exception handlers which do not cover a local raise. The default is that
3958 these warnings are given for units that contain exception handlers.
3962 *Disable warnings for No_Exception_Propagation mode.*
3964 This switch disables warnings for exception usage when pragma Restrictions
3965 (No_Exception_Propagation) is in effect.
3968 .. index:: -gnatwy (gcc)
3969 .. index:: Ada compatibility issues warnings
3972 *Activate warnings for Ada compatibility issues.*
3974 For the most part, newer versions of Ada are upwards compatible
3975 with older versions. For example, Ada 2005 programs will almost
3976 always work when compiled as Ada 2012.
3977 However there are some exceptions (for example the fact that
3978 ``some`` is now a reserved word in Ada 2012). This
3979 switch activates several warnings to help in identifying
3980 and correcting such incompatibilities. The default is that
3981 these warnings are generated. Note that at one point Ada 2005
3982 was called Ada 0Y, hence the choice of character.
3985 .. index:: -gnatwY (gcc)
3986 .. index:: Ada compatibility issues warnings
3989 *Disable warnings for Ada compatibility issues.*
3991 This switch suppresses the warnings intended to help in identifying
3992 incompatibilities between Ada language versions.
3995 .. index:: -gnatw.y (gcc)
3996 .. index:: Package spec needing body
3999 *Activate information messages for why package spec needs body.*
4001 There are a number of cases in which a package spec needs a body.
4002 For example, the use of pragma Elaborate_Body, or the declaration
4003 of a procedure specification requiring a completion. This switch
4004 causes information messages to be output showing why a package
4005 specification requires a body. This can be useful in the case of
4006 a large package specification which is unexpectedly requiring a
4007 body. The default is that such information messages are not output.
4010 .. index:: -gnatw.Y (gcc)
4011 .. index:: No information messages for why package spec needs body
4014 *Disable information messages for why package spec needs body.*
4016 This switch suppresses the output of information messages showing why
4017 a package specification needs a body.
4020 .. index:: -gnatwz (gcc)
4021 .. index:: Unchecked_Conversion warnings
4024 *Activate warnings on unchecked conversions.*
4026 This switch activates warnings for unchecked conversions
4027 where the types are known at compile time to have different
4028 sizes. The default is that such warnings are generated. Warnings are also
4029 generated for subprogram pointers with different conventions.
4032 .. index:: -gnatwZ (gcc)
4035 *Suppress warnings on unchecked conversions.*
4037 This switch suppresses warnings for unchecked conversions
4038 where the types are known at compile time to have different
4039 sizes or conventions.
4042 .. index:: -gnatw.z (gcc)
4043 .. index:: Size/Alignment warnings
4046 *Activate warnings for size not a multiple of alignment.*
4048 This switch activates warnings for cases of record types with
4049 specified ``Size`` and ``Alignment`` attributes where the
4050 size is not a multiple of the alignment, resulting in an object
4051 size that is greater than the specified size. The default
4052 is that such warnings are generated.
4055 .. index:: -gnatw.Z (gcc)
4056 .. index:: Size/Alignment warnings
4059 *Suppress warnings for size not a multiple of alignment.*
4061 This switch suppresses warnings for cases of record types with
4062 specified ``Size`` and ``Alignment`` attributes where the
4063 size is not a multiple of the alignment, resulting in an object
4064 size that is greater than the specified size.
4065 The warning can also be
4066 suppressed by giving an explicit ``Object_Size`` value.
4069 .. index:: -Wunused (gcc)
4072 The warnings controlled by the :switch:`-gnatw` switch are generated by
4073 the front end of the compiler. The GCC back end can provide
4074 additional warnings and they are controlled by the :switch:`-W` switch.
4075 For example, :switch:`-Wunused` activates back end
4076 warnings for entities that are declared but not referenced.
4079 .. index:: -Wuninitialized (gcc)
4081 :switch:`-Wuninitialized`
4082 Similarly, :switch:`-Wuninitialized` activates
4083 the back end warning for uninitialized variables. This switch must be
4084 used in conjunction with an optimization level greater than zero.
4087 .. index:: -Wstack-usage (gcc)
4089 :switch:`-Wstack-usage={len}`
4090 Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
4091 See :ref:`Static_Stack_Usage_Analysis` for details.
4094 .. index:: -Wall (gcc)
4097 This switch enables most warnings from the GCC back end.
4098 The code generator detects a number of warning situations that are missed
4099 by the GNAT front end, and this switch can be used to activate them.
4100 The use of this switch also sets the default front end warning mode to
4101 :switch:`-gnatwa`, that is, most front end warnings activated as well.
4107 Conversely, this switch suppresses warnings from the GCC back end.
4108 The use of this switch also sets the default front end warning mode to
4109 :switch:`-gnatws`, that is, front end warnings suppressed as well.
4112 .. index:: -Werror (gcc)
4115 This switch causes warnings from the GCC back end to be treated as
4116 errors. The warning string still appears, but the warning messages are
4117 counted as errors, and prevent the generation of an object file.
4120 A string of warning parameters can be used in the same parameter. For example::
4125 will turn on all optional warnings except for unrecognized pragma warnings,
4126 and also specify that warnings should be treated as errors.
4128 When no switch :switch:`-gnatw` is used, this is equivalent to:
4130 * :switch:`-gnatw.a`
4134 * :switch:`-gnatw.b`
4138 * :switch:`-gnatw.C`
4142 * :switch:`-gnatw.D`
4146 * :switch:`-gnatw.F`
4152 * :switch:`-gnatw.H`
4158 * :switch:`-gnatw.J`
4162 * :switch:`-gnatw.K`
4166 * :switch:`-gnatw.L`
4170 * :switch:`-gnatw.m`
4174 * :switch:`-gnatw.N`
4178 * :switch:`-gnatw.O`
4182 * :switch:`-gnatw.P`
4186 * :switch:`-gnatw.Q`
4190 * :switch:`-gnatw.R`
4192 * :switch:`-gnatw.S`
4196 * :switch:`-gnatw.t`
4200 * :switch:`-gnatw.U`
4204 * :switch:`-gnatw.v`
4208 * :switch:`-gnatw.W`
4212 * :switch:`-gnatw.X`
4216 * :switch:`-gnatw.Y`
4220 * :switch:`-gnatw.z`
4222 .. _Debugging_and_Assertion_Control:
4224 Debugging and Assertion Control
4225 -------------------------------
4229 .. index:: -gnata (gcc)
4234 .. index:: Assertions
4235 .. index:: Precondition
4236 .. index:: Postcondition
4237 .. index:: Type invariants
4238 .. index:: Subtype predicates
4240 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
4242 pragma Assertion_Policy (Check);
4244 Which is a shorthand for::
4246 pragma Assertion_Policy
4248 Static_Predicate => Check,
4249 Dynamic_Predicate => Check,
4253 Post'Class => Check,
4254 Type_Invariant => Check,
4255 Type_Invariant'Class => Check);
4257 The pragmas ``Assert`` and ``Debug`` normally have no effect and
4258 are ignored. This switch, where ``a`` stands for 'assert', causes
4259 pragmas ``Assert`` and ``Debug`` to be activated. This switch also
4260 causes preconditions, postconditions, subtype predicates, and
4261 type invariants to be activated.
4263 The pragmas have the form::
4265 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4266 pragma Debug (<procedure call>)
4267 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4268 pragma Predicate (<type-local-name>, <Boolean-expression>)
4269 pragma Precondition (<Boolean-expression>, <string-expression>)
4270 pragma Postcondition (<Boolean-expression>, <string-expression>)
4272 The aspects have the form::
4274 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4275 => <Boolean-expression>;
4277 The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
4278 If the result is ``True``, the pragma has no effect (other than
4279 possible side effects from evaluating the expression). If the result is
4280 ``False``, the exception ``Assert_Failure`` declared in the package
4281 ``System.Assertions`` is raised (passing ``static-string-expression``, if
4282 present, as the message associated with the exception). If no string
4283 expression is given, the default is a string containing the file name and
4284 line number of the pragma.
4286 The ``Debug`` pragma causes ``procedure`` to be called. Note that
4287 ``pragma Debug`` may appear within a declaration sequence, allowing
4288 debugging procedures to be called between declarations.
4290 For the aspect specification, the ``Boolean-expression`` is evaluated.
4291 If the result is ``True``, the aspect has no effect. If the result
4292 is ``False``, the exception ``Assert_Failure`` is raised.
4294 .. _Validity_Checking:
4299 .. index:: Validity Checking
4301 The Ada Reference Manual defines the concept of invalid values (see
4302 RM 13.9.1). The primary source of invalid values is uninitialized
4303 variables. A scalar variable that is left uninitialized may contain
4304 an invalid value; the concept of invalid does not apply to access or
4307 It is an error to read an invalid value, but the RM does not require
4308 run-time checks to detect such errors, except for some minimal
4309 checking to prevent erroneous execution (i.e. unpredictable
4310 behavior). This corresponds to the :switch:`-gnatVd` switch below,
4311 which is the default. For example, by default, if the expression of a
4312 case statement is invalid, it will raise Constraint_Error rather than
4313 causing a wild jump, and if an array index on the left-hand side of an
4314 assignment is invalid, it will raise Constraint_Error rather than
4315 overwriting an arbitrary memory location.
4317 The :switch:`-gnatVa` may be used to enable additional validity checks,
4318 which are not required by the RM. These checks are often very
4319 expensive (which is why the RM does not require them). These checks
4320 are useful in tracking down uninitialized variables, but they are
4321 not usually recommended for production builds, and in particular
4322 we do not recommend using these extra validity checking options in
4323 combination with optimization, since this can confuse the optimizer.
4324 If performance is a consideration, leading to the need to optimize,
4325 then the validity checking options should not be used.
4327 The other :switch:`-gnatV{x}` switches below allow finer-grained
4328 control; you can enable whichever validity checks you desire. However,
4329 for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
4330 default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
4331 sufficient for non-debugging use.
4333 The :switch:`-gnatB` switch tells the compiler to assume that all
4334 values are valid (that is, within their declared subtype range)
4335 except in the context of a use of the Valid attribute. This means
4336 the compiler can generate more efficient code, since the range
4337 of values is better known at compile time. However, an uninitialized
4338 variable can cause wild jumps and memory corruption in this mode.
4340 The :switch:`-gnatV{x}` switch allows control over the validity
4341 checking mode as described below.
4342 The ``x`` argument is a string of letters that
4343 indicate validity checks that are performed or not performed in addition
4344 to the default checks required by Ada as described above.
4347 .. index:: -gnatVa (gcc)
4350 *All validity checks.*
4352 All validity checks are turned on.
4353 That is, :switch:`-gnatVa` is
4354 equivalent to ``gnatVcdfimorst``.
4357 .. index:: -gnatVc (gcc)
4360 *Validity checks for copies.*
4362 The right hand side of assignments, and the initializing values of
4363 object declarations are validity checked.
4366 .. index:: -gnatVd (gcc)
4369 *Default (RM) validity checks.*
4371 Some validity checks are done by default following normal Ada semantics
4373 A check is done in case statements that the expression is within the range
4374 of the subtype. If it is not, Constraint_Error is raised.
4375 For assignments to array components, a check is done that the expression used
4376 as index is within the range. If it is not, Constraint_Error is raised.
4377 Both these validity checks may be turned off using switch :switch:`-gnatVD`.
4378 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
4379 switch :switch:`-gnatVd` will leave the checks turned on.
4380 Switch :switch:`-gnatVD` should be used only if you are sure that all such
4381 expressions have valid values. If you use this switch and invalid values
4382 are present, then the program is erroneous, and wild jumps or memory
4383 overwriting may occur.
4386 .. index:: -gnatVe (gcc)
4389 *Validity checks for elementary components.*
4391 In the absence of this switch, assignments to record or array components are
4392 not validity checked, even if validity checks for assignments generally
4393 (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not
4394 require valid data, but assignment of individual components does. So for
4395 example, there is a difference between copying the elements of an array with a
4396 slice assignment, compared to assigning element by element in a loop. This
4397 switch allows you to turn off validity checking for components, even when they
4398 are assigned component by component.
4401 .. index:: -gnatVf (gcc)
4404 *Validity checks for floating-point values.*
4406 In the absence of this switch, validity checking occurs only for discrete
4407 values. If :switch:`-gnatVf` is specified, then validity checking also applies
4408 for floating-point values, and NaNs and infinities are considered invalid,
4409 as well as out of range values for constrained types. Note that this means
4410 that standard IEEE infinity mode is not allowed. The exact contexts
4411 in which floating-point values are checked depends on the setting of other
4412 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
4413 (the order does not matter) specifies that floating-point parameters of mode
4414 ``in`` should be validity checked.
4417 .. index:: -gnatVi (gcc)
4420 *Validity checks for ``in`` mode parameters.*
4422 Arguments for parameters of mode ``in`` are validity checked in function
4423 and procedure calls at the point of call.
4426 .. index:: -gnatVm (gcc)
4429 *Validity checks for ``in out`` mode parameters.*
4431 Arguments for parameters of mode ``in out`` are validity checked in
4432 procedure calls at the point of call. The ``'m'`` here stands for
4433 modify, since this concerns parameters that can be modified by the call.
4434 Note that there is no specific option to test ``out`` parameters,
4435 but any reference within the subprogram will be tested in the usual
4436 manner, and if an invalid value is copied back, any reference to it
4437 will be subject to validity checking.
4440 .. index:: -gnatVn (gcc)
4443 *No validity checks.*
4445 This switch turns off all validity checking, including the default checking
4446 for case statements and left hand side subscripts. Note that the use of
4447 the switch :switch:`-gnatp` suppresses all run-time checks, including
4448 validity checks, and thus implies :switch:`-gnatVn`. When this switch
4449 is used, it cancels any other :switch:`-gnatV` previously issued.
4452 .. index:: -gnatVo (gcc)
4455 *Validity checks for operator and attribute operands.*
4457 Arguments for predefined operators and attributes are validity checked.
4458 This includes all operators in package ``Standard``,
4459 the shift operators defined as intrinsic in package ``Interfaces``
4460 and operands for attributes such as ``Pos``. Checks are also made
4461 on individual component values for composite comparisons, and on the
4462 expressions in type conversions and qualified expressions. Checks are
4463 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4466 .. index:: -gnatVp (gcc)
4469 *Validity checks for parameters.*
4471 This controls the treatment of parameters within a subprogram (as opposed
4472 to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing
4473 of parameters on a call. If either of these call options is used, then
4474 normally an assumption is made within a subprogram that the input arguments
4475 have been validity checking at the point of call, and do not need checking
4476 again within a subprogram). If :switch:`-gnatVp` is set, then this assumption
4477 is not made, and parameters are not assumed to be valid, so their validity
4478 will be checked (or rechecked) within the subprogram.
4481 .. index:: -gnatVr (gcc)
4484 *Validity checks for function returns.*
4486 The expression in ``return`` statements in functions is validity
4490 .. index:: -gnatVs (gcc)
4493 *Validity checks for subscripts.*
4495 All subscripts expressions are checked for validity, whether they appear
4496 on the right side or left side (in default mode only left side subscripts
4497 are validity checked).
4500 .. index:: -gnatVt (gcc)
4503 *Validity checks for tests.*
4505 Expressions used as conditions in ``if``, ``while`` or ``exit``
4506 statements are checked, as well as guard expressions in entry calls.
4509 The :switch:`-gnatV` switch may be followed by a string of letters
4510 to turn on a series of validity checking options.
4511 For example, :switch:`-gnatVcr`
4512 specifies that in addition to the default validity checking, copies and
4513 function return expressions are to be validity checked.
4514 In order to make it easier to specify the desired combination of effects,
4515 the upper case letters ``CDFIMORST`` may
4516 be used to turn off the corresponding lower case option.
4517 Thus :switch:`-gnatVaM` turns on all validity checking options except for
4518 checking of ``in out`` parameters.
4520 The specification of additional validity checking generates extra code (and
4521 in the case of :switch:`-gnatVa` the code expansion can be substantial).
4522 However, these additional checks can be very useful in detecting
4523 uninitialized variables, incorrect use of unchecked conversion, and other
4524 errors leading to invalid values. The use of pragma ``Initialize_Scalars``
4525 is useful in conjunction with the extra validity checking, since this
4526 ensures that wherever possible uninitialized variables have invalid values.
4528 See also the pragma ``Validity_Checks`` which allows modification of
4529 the validity checking mode at the program source level, and also allows for
4530 temporary disabling of validity checks.
4537 .. index:: Style checking
4539 .. index:: -gnaty (gcc)
4541 The :switch:`-gnatyx` switch causes the compiler to
4542 enforce specified style rules. A limited set of style rules has been used
4543 in writing the GNAT sources themselves. This switch allows user programs
4544 to activate all or some of these checks. If the source program fails a
4545 specified style check, an appropriate message is given, preceded by
4546 the character sequence '(style)'. This message does not prevent
4547 successful compilation (unless the :switch:`-gnatwe` switch is used).
4549 Note that this is by no means intended to be a general facility for
4550 checking arbitrary coding standards. It is simply an embedding of the
4551 style rules we have chosen for the GNAT sources. If you are starting
4552 a project which does not have established style standards, you may
4553 find it useful to adopt the entire set of GNAT coding standards, or
4554 some subset of them.
4556 .. only:: PRO or GPL
4558 If you already have an established set of coding
4559 standards, then the selected style checking options may
4560 indeed correspond to choices you have made, but for general checking
4561 of an existing set of coding rules, you should look to the gnatcheck
4562 tool, which is designed for that purpose.
4564 The string ``x`` is a sequence of letters or digits
4565 indicating the particular style
4566 checks to be performed. The following checks are defined:
4569 .. index:: -gnaty[0-9] (gcc)
4572 *Specify indentation level.*
4574 If a digit from 1-9 appears
4575 in the string after :switch:`-gnaty`
4576 then proper indentation is checked, with the digit indicating the
4577 indentation level required. A value of zero turns off this style check.
4578 The general style of required indentation is as specified by
4579 the examples in the Ada Reference Manual. Full line comments must be
4580 aligned with the ``--`` starting on a column that is a multiple of
4581 the alignment level, or they may be aligned the same way as the following
4582 non-blank line (this is useful when full line comments appear in the middle
4583 of a statement, or they may be aligned with the source line on the previous
4586 .. index:: -gnatya (gcc)
4589 *Check attribute casing.*
4591 Attribute names, including the case of keywords such as ``digits``
4592 used as attributes names, must be written in mixed case, that is, the
4593 initial letter and any letter following an underscore must be uppercase.
4594 All other letters must be lowercase.
4597 .. index:: -gnatyA (gcc)
4600 *Use of array index numbers in array attributes.*
4602 When using the array attributes First, Last, Range,
4603 or Length, the index number must be omitted for one-dimensional arrays
4604 and is required for multi-dimensional arrays.
4607 .. index:: -gnatyb (gcc)
4610 *Blanks not allowed at statement end.*
4612 Trailing blanks are not allowed at the end of statements. The purpose of this
4613 rule, together with h (no horizontal tabs), is to enforce a canonical format
4614 for the use of blanks to separate source tokens.
4617 .. index:: -gnatyB (gcc)
4620 *Check Boolean operators.*
4622 The use of AND/OR operators is not permitted except in the cases of modular
4623 operands, array operands, and simple stand-alone boolean variables or
4624 boolean constants. In all other cases ``and then``/`or else` are
4628 .. index:: -gnatyc (gcc)
4631 *Check comments, double space.*
4633 Comments must meet the following set of rules:
4635 * The ``--`` that starts the column must either start in column one,
4636 or else at least one blank must precede this sequence.
4638 * Comments that follow other tokens on a line must have at least one blank
4639 following the ``--`` at the start of the comment.
4641 * Full line comments must have at least two blanks following the
4642 ``--`` that starts the comment, with the following exceptions.
4644 * A line consisting only of the ``--`` characters, possibly preceded
4645 by blanks is permitted.
4647 * A comment starting with ``--x`` where ``x`` is a special character
4649 This allows proper processing of the output from specialized tools
4650 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
4652 language (where ``--#`` is used). For the purposes of this rule, a
4653 special character is defined as being in one of the ASCII ranges
4654 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
4655 Note that this usage is not permitted
4656 in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
4658 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4659 permitted. This allows the construction of box comments where lines of minus
4660 signs are used to form the top and bottom of the box.
4662 * A comment that starts and ends with ``--`` is permitted as long as at
4663 least one blank follows the initial ``--``. Together with the preceding
4664 rule, this allows the construction of box comments, as shown in the following
4669 ---------------------------
4670 -- This is a box comment --
4671 -- with two text lines. --
4672 ---------------------------
4675 .. index:: -gnatyC (gcc)
4678 *Check comments, single space.*
4680 This is identical to ``c`` except that only one space
4681 is required following the ``--`` of a comment instead of two.
4684 .. index:: -gnatyd (gcc)
4687 *Check no DOS line terminators present.*
4689 All lines must be terminated by a single ASCII.LF
4690 character (in particular the DOS line terminator sequence CR/LF is not
4694 .. index:: -gnatye (gcc)
4697 *Check end/exit labels.*
4699 Optional labels on ``end`` statements ending subprograms and on
4700 ``exit`` statements exiting named loops, are required to be present.
4703 .. index:: -gnatyf (gcc)
4706 *No form feeds or vertical tabs.*
4708 Neither form feeds nor vertical tab characters are permitted
4712 .. index:: -gnatyg (gcc)
4717 The set of style check switches is set to match that used by the GNAT sources.
4718 This may be useful when developing code that is eventually intended to be
4719 incorporated into GNAT. Currently this is equivalent to :switch:`-gnatwydISux`)
4720 but additional style switches may be added to this set in the future without
4724 .. index:: -gnatyh (gcc)
4727 *No horizontal tabs.*
4729 Horizontal tab characters are not permitted in the source text.
4730 Together with the b (no blanks at end of line) check, this
4731 enforces a canonical form for the use of blanks to separate
4735 .. index:: -gnatyi (gcc)
4738 *Check if-then layout.*
4740 The keyword ``then`` must appear either on the same
4741 line as corresponding ``if``, or on a line on its own, lined
4742 up under the ``if``.
4745 .. index:: -gnatyI (gcc)
4748 *check mode IN keywords.*
4750 Mode ``in`` (the default mode) is not
4751 allowed to be given explicitly. ``in out`` is fine,
4752 but not ``in`` on its own.
4755 .. index:: -gnatyk (gcc)
4758 *Check keyword casing.*
4760 All keywords must be in lower case (with the exception of keywords
4761 such as ``digits`` used as attribute names to which this check
4765 .. index:: -gnatyl (gcc)
4770 Layout of statement and declaration constructs must follow the
4771 recommendations in the Ada Reference Manual, as indicated by the
4772 form of the syntax rules. For example an ``else`` keyword must
4773 be lined up with the corresponding ``if`` keyword.
4775 There are two respects in which the style rule enforced by this check
4776 option are more liberal than those in the Ada Reference Manual. First
4777 in the case of record declarations, it is permissible to put the
4778 ``record`` keyword on the same line as the ``type`` keyword, and
4779 then the ``end`` in ``end record`` must line up under ``type``.
4780 This is also permitted when the type declaration is split on two lines.
4781 For example, any of the following three layouts is acceptable:
4802 Second, in the case of a block statement, a permitted alternative
4803 is to put the block label on the same line as the ``declare`` or
4804 ``begin`` keyword, and then line the ``end`` keyword up under
4805 the block label. For example both the following are permitted:
4822 The same alternative format is allowed for loops. For example, both of
4823 the following are permitted:
4827 Clear : while J < 10 loop
4837 .. index:: -gnatyLnnn (gcc)
4840 *Set maximum nesting level.*
4842 The maximum level of nesting of constructs (including subprograms, loops,
4843 blocks, packages, and conditionals) may not exceed the given value
4844 *nnn*. A value of zero disconnects this style check.
4847 .. index:: -gnatym (gcc)
4850 *Check maximum line length.*
4852 The length of source lines must not exceed 79 characters, including
4853 any trailing blanks. The value of 79 allows convenient display on an
4854 80 character wide device or window, allowing for possible special
4855 treatment of 80 character lines. Note that this count is of
4856 characters in the source text. This means that a tab character counts
4857 as one character in this count and a wide character sequence counts as
4858 a single character (however many bytes are needed in the encoding).
4861 .. index:: -gnatyMnnn (gcc)
4864 *Set maximum line length.*
4866 The length of lines must not exceed the
4867 given value *nnn*. The maximum value that can be specified is 32767.
4868 If neither style option for setting the line length is used, then the
4869 default is 255. This also controls the maximum length of lexical elements,
4870 where the only restriction is that they must fit on a single line.
4873 .. index:: -gnatyn (gcc)
4876 *Check casing of entities in Standard.*
4878 Any identifier from Standard must be cased
4879 to match the presentation in the Ada Reference Manual (for example,
4880 ``Integer`` and ``ASCII.NUL``).
4883 .. index:: -gnatyN (gcc)
4886 *Turn off all style checks.*
4888 All style check options are turned off.
4891 .. index:: -gnatyo (gcc)
4894 *Check order of subprogram bodies.*
4896 All subprogram bodies in a given scope
4897 (e.g., a package body) must be in alphabetical order. The ordering
4898 rule uses normal Ada rules for comparing strings, ignoring casing
4899 of letters, except that if there is a trailing numeric suffix, then
4900 the value of this suffix is used in the ordering (e.g., Junk2 comes
4904 .. index:: -gnatyO (gcc)
4907 *Check that overriding subprograms are explicitly marked as such.*
4909 This applies to all subprograms of a derived type that override a primitive
4910 operation of the type, for both tagged and untagged types. In particular,
4911 the declaration of a primitive operation of a type extension that overrides
4912 an inherited operation must carry an overriding indicator. Another case is
4913 the declaration of a function that overrides a predefined operator (such
4914 as an equality operator).
4917 .. index:: -gnatyp (gcc)
4920 *Check pragma casing.*
4922 Pragma names must be written in mixed case, that is, the
4923 initial letter and any letter following an underscore must be uppercase.
4924 All other letters must be lowercase. An exception is that SPARK_Mode is
4925 allowed as an alternative for Spark_Mode.
4928 .. index:: -gnatyr (gcc)
4933 All identifier references must be cased in the same way as the
4934 corresponding declaration. No specific casing style is imposed on
4935 identifiers. The only requirement is for consistency of references
4939 .. index:: -gnatys (gcc)
4942 *Check separate specs.*
4944 Separate declarations ('specs') are required for subprograms (a
4945 body is not allowed to serve as its own declaration). The only
4946 exception is that parameterless library level procedures are
4947 not required to have a separate declaration. This exception covers
4948 the most frequent form of main program procedures.
4951 .. index:: -gnatyS (gcc)
4954 *Check no statements after then/else.*
4956 No statements are allowed
4957 on the same line as a ``then`` or ``else`` keyword following the
4958 keyword in an ``if`` statement. ``or else`` and ``and then`` are not
4959 affected, and a special exception allows a pragma to appear after ``else``.
4962 .. index:: -gnatyt (gcc)
4965 *Check token spacing.*
4967 The following token spacing rules are enforced:
4969 * The keywords ``abs`` and ``not`` must be followed by a space.
4971 * The token ``=>`` must be surrounded by spaces.
4973 * The token ``<>`` must be preceded by a space or a left parenthesis.
4975 * Binary operators other than ``**`` must be surrounded by spaces.
4976 There is no restriction on the layout of the ``**`` binary operator.
4978 * Colon must be surrounded by spaces.
4980 * Colon-equal (assignment, initialization) must be surrounded by spaces.
4982 * Comma must be the first non-blank character on the line, or be
4983 immediately preceded by a non-blank character, and must be followed
4986 * If the token preceding a left parenthesis ends with a letter or digit, then
4987 a space must separate the two tokens.
4989 * If the token following a right parenthesis starts with a letter or digit, then
4990 a space must separate the two tokens.
4992 * A right parenthesis must either be the first non-blank character on
4993 a line, or it must be preceded by a non-blank character.
4995 * A semicolon must not be preceded by a space, and must not be followed by
4996 a non-blank character.
4998 * A unary plus or minus may not be followed by a space.
5000 * A vertical bar must be surrounded by spaces.
5002 Exactly one blank (and no other white space) must appear between
5003 a ``not`` token and a following ``in`` token.
5006 .. index:: -gnatyu (gcc)
5009 *Check unnecessary blank lines.*
5011 Unnecessary blank lines are not allowed. A blank line is considered
5012 unnecessary if it appears at the end of the file, or if more than
5013 one blank line occurs in sequence.
5016 .. index:: -gnatyx (gcc)
5019 *Check extra parentheses.*
5021 Unnecessary extra level of parentheses (C-style) are not allowed
5022 around conditions in ``if`` statements, ``while`` statements and
5023 ``exit`` statements.
5026 .. index:: -gnatyy (gcc)
5029 *Set all standard style check options.*
5031 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
5032 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
5033 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
5034 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
5037 .. index:: -gnaty- (gcc)
5040 *Remove style check options.*
5042 This causes any subsequent options in the string to act as canceling the
5043 corresponding style check option. To cancel maximum nesting level control,
5044 use the ``L`` parameter without any integer value after that, because any
5045 digit following *-* in the parameter string of the :switch:`-gnaty`
5046 option will be treated as canceling the indentation check. The same is true
5047 for the ``M`` parameter. ``y`` and ``N`` parameters are not
5051 .. index:: -gnaty+ (gcc)
5054 *Enable style check options.*
5056 This causes any subsequent options in the string to enable the corresponding
5057 style check option. That is, it cancels the effect of a previous -,
5061 .. end of switch description (leave this comment to ease automatic parsing for
5064 In the above rules, appearing in column one is always permitted, that is,
5065 counts as meeting either a requirement for a required preceding space,
5066 or as meeting a requirement for no preceding space.
5068 Appearing at the end of a line is also always permitted, that is, counts
5069 as meeting either a requirement for a following space, or as meeting
5070 a requirement for no following space.
5072 If any of these style rules is violated, a message is generated giving
5073 details on the violation. The initial characters of such messages are
5074 always '`(style)`'. Note that these messages are treated as warning
5075 messages, so they normally do not prevent the generation of an object
5076 file. The :switch:`-gnatwe` switch can be used to treat warning messages,
5077 including style messages, as fatal errors.
5079 The switch :switch:`-gnaty` on its own (that is not
5080 followed by any letters or digits) is equivalent
5081 to the use of :switch:`-gnatyy` as described above, that is all
5082 built-in standard style check options are enabled.
5084 The switch :switch:`-gnatyN` clears any previously set style checks.
5086 .. _Run-Time_Checks:
5091 .. index:: Division by zero
5093 .. index:: Access before elaboration
5095 .. index:: Checks, division by zero
5097 .. index:: Checks, access before elaboration
5099 .. index:: Checks, stack overflow checking
5101 By default, the following checks are suppressed: stack overflow
5102 checks, and checks for access before elaboration on subprogram
5103 calls. All other checks, including overflow checks, range checks and
5104 array bounds checks, are turned on by default. The following ``gcc``
5105 switches refine this default behavior.
5107 .. index:: -gnatp (gcc)
5110 .. index:: Suppressing checks
5112 .. index:: Checks, suppressing
5114 This switch causes the unit to be compiled
5115 as though ``pragma Suppress (All_checks)``
5116 had been present in the source. Validity checks are also eliminated (in
5117 other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
5118 Use this switch to improve the performance
5119 of the code at the expense of safety in the presence of invalid data or
5122 Note that when checks are suppressed, the compiler is allowed, but not
5123 required, to omit the checking code. If the run-time cost of the
5124 checking code is zero or near-zero, the compiler will generate it even
5125 if checks are suppressed. In particular, if the compiler can prove
5126 that a certain check will necessarily fail, it will generate code to
5127 do an unconditional 'raise', even if checks are suppressed. The
5128 compiler warns in this case. Another case in which checks may not be
5129 eliminated is when they are embedded in certain run-time routines such
5130 as math library routines.
5132 Of course, run-time checks are omitted whenever the compiler can prove
5133 that they will not fail, whether or not checks are suppressed.
5135 Note that if you suppress a check that would have failed, program
5136 execution is erroneous, which means the behavior is totally
5137 unpredictable. The program might crash, or print wrong answers, or
5138 do anything else. It might even do exactly what you wanted it to do
5139 (and then it might start failing mysteriously next week or next
5140 year). The compiler will generate code based on the assumption that
5141 the condition being checked is true, which can result in erroneous
5142 execution if that assumption is wrong.
5144 The checks subject to suppression include all the checks defined by the Ada
5145 standard, the additional implementation defined checks ``Alignment_Check``,
5146 ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``,
5147 and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``.
5148 Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option.
5150 If the code depends on certain checks being active, you can use
5151 pragma ``Unsuppress`` either as a configuration pragma or as
5152 a local pragma to make sure that a specified check is performed
5153 even if ``gnatp`` is specified.
5155 The :switch:`-gnatp` switch has no effect if a subsequent
5156 :switch:`-gnat-p` switch appears.
5159 .. index:: -gnat-p (gcc)
5160 .. index:: Suppressing checks
5161 .. index:: Checks, suppressing
5165 This switch cancels the effect of a previous ``gnatp`` switch.
5168 .. index:: -gnato?? (gcc)
5169 .. index:: Overflow checks
5170 .. index:: Overflow mode
5171 .. index:: Check, overflow
5174 This switch controls the mode used for computing intermediate
5175 arithmetic integer operations, and also enables overflow checking.
5176 For a full description of overflow mode and checking control, see
5177 the 'Overflow Check Handling in GNAT' appendix in this
5180 Overflow checks are always enabled by this switch. The argument
5181 controls the mode, using the codes
5185 In STRICT mode, intermediate operations are always done using the
5186 base type, and overflow checking ensures that the result is within
5187 the base type range.
5191 In MINIMIZED mode, overflows in intermediate operations are avoided
5192 where possible by using a larger integer type for the computation
5193 (typically ``Long_Long_Integer``). Overflow checking ensures that
5194 the result fits in this larger integer type.
5198 In ELIMINATED mode, overflows in intermediate operations are avoided
5199 by using multi-precision arithmetic. In this case, overflow checking
5200 has no effect on intermediate operations (since overflow is impossible).
5202 If two digits are present after :switch:`-gnato` then the first digit
5203 sets the mode for expressions outside assertions, and the second digit
5204 sets the mode for expressions within assertions. Here assertions is used
5205 in the technical sense (which includes for example precondition and
5206 postcondition expressions).
5208 If one digit is present, the corresponding mode is applicable to both
5209 expressions within and outside assertion expressions.
5211 If no digits are present, the default is to enable overflow checks
5212 and set STRICT mode for both kinds of expressions. This is compatible
5213 with the use of :switch:`-gnato` in previous versions of GNAT.
5215 .. index:: Machine_Overflows
5217 Note that the :switch:`-gnato??` switch does not affect the code generated
5218 for any floating-point operations; it applies only to integer semantics.
5219 For floating-point, GNAT has the ``Machine_Overflows``
5220 attribute set to ``False`` and the normal mode of operation is to
5221 generate IEEE NaN and infinite values on overflow or invalid operations
5222 (such as dividing 0.0 by 0.0).
5224 The reason that we distinguish overflow checking from other kinds of
5225 range constraint checking is that a failure of an overflow check, unlike
5226 for example the failure of a range check, can result in an incorrect
5227 value, but cannot cause random memory destruction (like an out of range
5228 subscript), or a wild jump (from an out of range case value). Overflow
5229 checking is also quite expensive in time and space, since in general it
5230 requires the use of double length arithmetic.
5232 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
5233 so overflow checking is performed in STRICT mode by default.
5236 .. index:: -gnatE (gcc)
5237 .. index:: Elaboration checks
5238 .. index:: Check, elaboration
5241 Enables dynamic checks for access-before-elaboration
5242 on subprogram calls and generic instantiations.
5243 Note that :switch:`-gnatE` is not necessary for safety, because in the
5244 default mode, GNAT ensures statically that the checks would not fail.
5245 For full details of the effect and use of this switch,
5246 :ref:`Compiling_with_gcc`.
5249 .. index:: -fstack-check (gcc)
5250 .. index:: Stack Overflow Checking
5251 .. index:: Checks, stack overflow checking
5253 :switch:`-fstack-check`
5254 Activates stack overflow checking. For full details of the effect and use of
5255 this switch see :ref:`Stack_Overflow_Checking`.
5257 .. index:: Unsuppress
5259 The setting of these switches only controls the default setting of the
5260 checks. You may modify them using either ``Suppress`` (to remove
5261 checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
5265 .. _Using_gcc_for_Syntax_Checking:
5267 Using ``gcc`` for Syntax Checking
5268 ---------------------------------
5270 .. index:: -gnats (gcc)
5273 The ``s`` stands for 'syntax'.
5275 Run GNAT in syntax checking only mode. For
5276 example, the command
5280 $ gcc -c -gnats x.adb
5282 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5283 series of files in a single command
5284 , and can use wild cards to specify such a group of files.
5285 Note that you must specify the :switch:`-c` (compile
5286 only) flag in addition to the :switch:`-gnats` flag.
5288 You may use other switches in conjunction with :switch:`-gnats`. In
5289 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
5290 format of any generated error messages.
5292 When the source file is empty or contains only empty lines and/or comments,
5293 the output is a warning:
5298 $ gcc -c -gnats -x ada toto.txt
5299 toto.txt:1:01: warning: empty file, contains no compilation units
5303 Otherwise, the output is simply the error messages, if any. No object file or
5304 ALI file is generated by a syntax-only compilation. Also, no units other
5305 than the one specified are accessed. For example, if a unit ``X``
5306 |withs| a unit ``Y``, compiling unit ``X`` in syntax
5307 check only mode does not access the source file containing unit
5310 .. index:: Multiple units, syntax checking
5312 Normally, GNAT allows only a single unit in a source file. However, this
5313 restriction does not apply in syntax-check-only mode, and it is possible
5314 to check a file containing multiple compilation units concatenated
5315 together. This is primarily used by the ``gnatchop`` utility
5316 (:ref:`Renaming_Files_with_gnatchop`).
5318 .. _Using_gcc_for_Semantic_Checking:
5320 Using ``gcc`` for Semantic Checking
5321 -----------------------------------
5325 .. index:: -gnatc (gcc)
5328 The ``c`` stands for 'check'.
5329 Causes the compiler to operate in semantic check mode,
5330 with full checking for all illegalities specified in the
5331 Ada Reference Manual, but without generation of any object code
5332 (no object file is generated).
5334 Because dependent files must be accessed, you must follow the GNAT
5335 semantic restrictions on file structuring to operate in this mode:
5337 * The needed source files must be accessible
5338 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5340 * Each file must contain only one compilation unit.
5342 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5344 The output consists of error messages as appropriate. No object file is
5345 generated. An :file:`ALI` file is generated for use in the context of
5346 cross-reference tools, but this file is marked as not being suitable
5347 for binding (since no object file is generated).
5348 The checking corresponds exactly to the notion of
5349 legality in the Ada Reference Manual.
5351 Any unit can be compiled in semantics-checking-only mode, including
5352 units that would not normally be compiled (subunits,
5353 and specifications where a separate body is present).
5355 .. _Compiling_Different_Versions_of_Ada:
5357 Compiling Different Versions of Ada
5358 -----------------------------------
5360 The switches described in this section allow you to explicitly specify
5361 the version of the Ada language that your programs are written in.
5362 The default mode is Ada 2012,
5363 but you can also specify Ada 95, Ada 2005 mode, or
5364 indicate Ada 83 compatibility mode.
5367 .. index:: Compatibility with Ada 83
5368 .. index:: -gnat83 (gcc)
5369 .. index:: ACVC, Ada 83 tests
5370 .. index:: Ada 83 mode
5372 :switch:`-gnat83` (Ada 83 Compatibility Mode)
5373 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5374 specifies that the program is to be compiled in Ada 83 mode. With
5375 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5376 semantics where this can be done easily.
5377 It is not possible to guarantee this switch does a perfect
5378 job; some subtle tests, such as are
5379 found in earlier ACVC tests (and that have been removed from the ACATS suite
5380 for Ada 95), might not compile correctly.
5381 Nevertheless, this switch may be useful in some circumstances, for example
5382 where, due to contractual reasons, existing code needs to be maintained
5383 using only Ada 83 features.
5385 With few exceptions (most notably the need to use ``<>`` on
5386 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5387 the use of the new Ada 95 / Ada 2005
5388 reserved words, and the use of packages
5389 with optional bodies), it is not necessary to specify the
5390 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
5391 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5392 a correct Ada 83 program is usually also a correct program
5393 in these later versions of the language standard. For further information
5394 please refer to the *Compatibility and Porting Guide* chapter in the
5395 :title:`GNAT Reference Manual`.
5398 .. index:: -gnat95 (gcc)
5399 .. index:: Ada 95 mode
5401 :switch:`-gnat95` (Ada 95 mode)
5402 This switch directs the compiler to implement the Ada 95 version of the
5404 Since Ada 95 is almost completely upwards
5405 compatible with Ada 83, Ada 83 programs may generally be compiled using
5406 this switch (see the description of the :switch:`-gnat83` switch for further
5407 information about Ada 83 mode).
5408 If an Ada 2005 program is compiled in Ada 95 mode,
5409 uses of the new Ada 2005 features will cause error
5410 messages or warnings.
5412 This switch also can be used to cancel the effect of a previous
5413 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
5414 switch earlier in the command line.
5417 .. index:: -gnat05 (gcc)
5418 .. index:: -gnat2005 (gcc)
5419 .. index:: Ada 2005 mode
5421 :switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
5422 This switch directs the compiler to implement the Ada 2005 version of the
5423 language, as documented in the official Ada standards document.
5424 Since Ada 2005 is almost completely upwards
5425 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5426 may generally be compiled using this switch (see the description of the
5427 :switch:`-gnat83` and :switch:`-gnat95` switches for further
5431 .. index:: -gnat12 (gcc)
5432 .. index:: -gnat2012 (gcc)
5433 .. index:: Ada 2012 mode
5435 :switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
5436 This switch directs the compiler to implement the Ada 2012 version of the
5437 language (also the default).
5438 Since Ada 2012 is almost completely upwards
5439 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5440 Ada 83 and Ada 95 programs
5441 may generally be compiled using this switch (see the description of the
5442 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
5443 for further information).
5446 .. index:: -gnatX (gcc)
5447 .. index:: Ada language extensions
5448 .. index:: GNAT extensions
5450 :switch:`-gnatX` (Enable GNAT Extensions)
5451 This switch directs the compiler to implement the latest version of the
5452 language (currently Ada 2012) and also to enable certain GNAT implementation
5453 extensions that are not part of any Ada standard. For a full list of these
5454 extensions, see the GNAT reference manual.
5457 .. _Character_Set_Control:
5459 Character Set Control
5460 ---------------------
5462 .. index:: -gnati (gcc)
5465 Normally GNAT recognizes the Latin-1 character set in source program
5466 identifiers, as described in the Ada Reference Manual.
5468 GNAT to recognize alternate character sets in identifiers. ``c`` is a
5469 single character indicating the character set, as follows:
5471 ========== ======================================================
5472 *1* ISO 8859-1 (Latin-1) identifiers
5473 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5474 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5475 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5476 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5477 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5478 *p* IBM PC letters (code page 437) allowed in identifiers
5479 *8* IBM PC letters (code page 850) allowed in identifiers
5480 *f* Full upper-half codes allowed in identifiers
5481 *n* No upper-half codes allowed in identifiers
5482 *w* Wide-character codes (that is, codes greater than 255)
5483 allowed in identifiers
5484 ========== ======================================================
5486 See :ref:`Foreign_Language_Representation` for full details on the
5487 implementation of these character sets.
5490 .. index:: -gnatW (gcc)
5493 Specify the method of encoding for wide characters.
5494 ``e`` is one of the following:
5496 ========== ======================================================
5497 *h* Hex encoding (brackets coding also recognized)
5498 *u* Upper half encoding (brackets encoding also recognized)
5499 *s* Shift/JIS encoding (brackets encoding also recognized)
5500 *e* EUC encoding (brackets encoding also recognized)
5501 *8* UTF-8 encoding (brackets encoding also recognized)
5502 *b* Brackets encoding only (default value)
5503 ========== ======================================================
5505 For full details on these encoding
5506 methods see :ref:`Wide_Character_Encodings`.
5507 Note that brackets coding is always accepted, even if one of the other
5508 options is specified, so for example :switch:`-gnatW8` specifies that both
5509 brackets and UTF-8 encodings will be recognized. The units that are
5510 with'ed directly or indirectly will be scanned using the specified
5511 representation scheme, and so if one of the non-brackets scheme is
5512 used, it must be used consistently throughout the program. However,
5513 since brackets encoding is always recognized, it may be conveniently
5514 used in standard libraries, allowing these libraries to be used with
5515 any of the available coding schemes.
5517 Note that brackets encoding only applies to program text. Within comments,
5518 brackets are considered to be normal graphic characters, and bracket sequences
5519 are never recognized as wide characters.
5521 If no :switch:`-gnatW?` parameter is present, then the default
5522 representation is normally Brackets encoding only. However, if the
5523 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5524 byte order mark or BOM for UTF-8), then these three characters are
5525 skipped and the default representation for the file is set to UTF-8.
5527 Note that the wide character representation that is specified (explicitly
5528 or by default) for the main program also acts as the default encoding used
5529 for Wide_Text_IO files if not specifically overridden by a WCEM form
5533 When no :switch:`-gnatW?` is specified, then characters (other than wide
5534 characters represented using brackets notation) are treated as 8-bit
5535 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5536 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5537 characters in the range 16#00#..16#1F# are not accepted in program text
5538 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5539 in program text, but allowed and ignored in comments. Note in particular
5540 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5541 as an end of line in this default mode. If your source program contains
5542 instances of the NEL character used as a line terminator,
5543 you must use UTF-8 encoding for the whole
5544 source program. In default mode, all lines must be ended by a standard
5545 end of line sequence (CR, CR/LF, or LF).
5547 Note that the convention of simply accepting all upper half characters in
5548 comments means that programs that use standard ASCII for program text, but
5549 UTF-8 encoding for comments are accepted in default mode, providing that the
5550 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5551 This is a common mode for many programs with foreign language comments.
5553 .. _File_Naming_Control:
5558 .. index:: -gnatk (gcc)
5561 Activates file name 'krunching'. ``n``, a decimal integer in the range
5562 1-999, indicates the maximum allowable length of a file name (not
5563 including the :file:`.ads` or :file:`.adb` extension). The default is not
5564 to enable file name krunching.
5566 For the source file naming rules, :ref:`File_Naming_Rules`.
5568 .. _Subprogram_Inlining_Control:
5570 Subprogram Inlining Control
5571 ---------------------------
5573 .. index:: -gnatn (gcc)
5575 :switch:`-gnatn[12]`
5576 The ``n`` here is intended to suggest the first syllable of the word 'inline'.
5577 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
5578 actually occur, optimization must be enabled and, by default, inlining of
5579 subprograms across units is not performed. If you want to additionally
5580 enable inlining of subprograms specified by pragma ``Inline`` across units,
5581 you must also specify this switch.
5583 In the absence of this switch, GNAT does not attempt inlining across units
5584 and does not access the bodies of subprograms for which ``pragma Inline`` is
5585 specified if they are not in the current unit.
5587 You can optionally specify the inlining level: 1 for moderate inlining across
5588 units, which is a good compromise between compilation times and performances
5589 at run time, or 2 for full inlining across units, which may bring about
5590 longer compilation times. If no inlining level is specified, the compiler will
5591 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
5592 :switch:`-Os` and 2 for :switch:`-O3`.
5594 If you specify this switch the compiler will access these bodies,
5595 creating an extra source dependency for the resulting object file, and
5596 where possible, the call will be inlined.
5597 For further details on when inlining is possible
5598 see :ref:`Inlining_of_Subprograms`.
5601 .. index:: -gnatN (gcc)
5604 This switch activates front-end inlining which also
5605 generates additional dependencies.
5607 When using a gcc-based back end (in practice this means using any version
5608 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
5609 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
5610 Historically front end inlining was more extensive than the gcc back end
5611 inlining, but that is no longer the case.
5613 .. _Auxiliary_Output_Control:
5615 Auxiliary Output Control
5616 ------------------------
5618 .. index:: -gnatt (gcc)
5619 .. index:: Writing internal trees
5620 .. index:: Internal trees, writing to file
5623 Causes GNAT to write the internal tree for a unit to a file (with the
5624 extension :file:`.adt`.
5625 This not normally required, but is used by separate analysis tools.
5627 these tools do the necessary compilations automatically, so you should
5628 not have to specify this switch in normal operation.
5629 Note that the combination of switches :switch:`-gnatct`
5630 generates a tree in the form required by ASIS applications.
5633 .. index:: -gnatu (gcc)
5636 Print a list of units required by this compilation on :file:`stdout`.
5637 The listing includes all units on which the unit being compiled depends
5638 either directly or indirectly.
5641 .. index:: -pass-exit-codes (gcc)
5643 :switch:`-pass-exit-codes`
5644 If this switch is not used, the exit code returned by ``gcc`` when
5645 compiling multiple files indicates whether all source files have
5646 been successfully used to generate object files or not.
5648 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
5649 exit status and allows an integrated development environment to better
5650 react to a compilation failure. Those exit status are:
5652 ========== ======================================================
5653 *5* There was an error in at least one source file.
5654 *3* At least one source file did not generate an object file.
5655 *2* The compiler died unexpectedly (internal error for example).
5656 *0* An object file has been generated for every source file.
5657 ========== ======================================================
5659 .. _Debugging_Control:
5664 .. index:: Debugging options
5667 .. index:: -gnatd (gcc)
5670 Activate internal debugging switches. ``x`` is a letter or digit, or
5671 string of letters or digits, which specifies the type of debugging
5672 outputs desired. Normally these are used only for internal development
5673 or system debugging purposes. You can find full documentation for these
5674 switches in the body of the ``Debug`` unit in the compiler source
5675 file :file:`debug.adb`.
5678 .. index:: -gnatG (gcc)
5680 :switch:`-gnatG[={nn}]`
5681 This switch causes the compiler to generate auxiliary output containing
5682 a pseudo-source listing of the generated expanded code. Like most Ada
5683 compilers, GNAT works by first transforming the high level Ada code into
5684 lower level constructs. For example, tasking operations are transformed
5685 into calls to the tasking run-time routines. A unique capability of GNAT
5686 is to list this expanded code in a form very close to normal Ada source.
5687 This is very useful in understanding the implications of various Ada
5688 usage on the efficiency of the generated code. There are many cases in
5689 Ada (e.g., the use of controlled types), where simple Ada statements can
5690 generate a lot of run-time code. By using :switch:`-gnatG` you can identify
5691 these cases, and consider whether it may be desirable to modify the coding
5692 approach to improve efficiency.
5694 The optional parameter ``nn`` if present after -gnatG specifies an
5695 alternative maximum line length that overrides the normal default of 72.
5696 This value is in the range 40-999999, values less than 40 being silently
5697 reset to 40. The equal sign is optional.
5699 The format of the output is very similar to standard Ada source, and is
5700 easily understood by an Ada programmer. The following special syntactic
5701 additions correspond to low level features used in the generated code that
5702 do not have any exact analogies in pure Ada source form. The following
5703 is a partial list of these special constructions. See the spec
5704 of package ``Sprint`` in file :file:`sprint.ads` for a full list.
5706 .. index:: -gnatL (gcc)
5708 If the switch :switch:`-gnatL` is used in conjunction with
5709 :switch:`-gnatG`, then the original source lines are interspersed
5710 in the expanded source (as comment lines with the original line number).
5712 :samp:`new {xxx} [storage_pool = {yyy}]`
5713 Shows the storage pool being used for an allocator.
5716 :samp:`at end {procedure-name};`
5717 Shows the finalization (cleanup) procedure for a scope.
5720 :samp:`(if {expr} then {expr} else {expr})`
5721 Conditional expression equivalent to the ``x?y:z`` construction in C.
5724 :samp:`{target}^({source})`
5725 A conversion with floating-point truncation instead of rounding.
5728 :samp:`{target}?({source})`
5729 A conversion that bypasses normal Ada semantic checking. In particular
5730 enumeration types and fixed-point types are treated simply as integers.
5733 :samp:`{target}?^({source})`
5734 Combines the above two cases.
5739 :samp:`{x} #mod {y}`
5743 :samp:`{x} #rem {y}`
5744 A division or multiplication of fixed-point values which are treated as
5745 integers without any kind of scaling.
5748 :samp:`free {expr} [storage_pool = {xxx}]`
5749 Shows the storage pool associated with a ``free`` statement.
5752 :samp:`[subtype or type declaration]`
5753 Used to list an equivalent declaration for an internally generated
5754 type that is referenced elsewhere in the listing.
5757 :samp:`freeze {type-name} [{actions}]`
5758 Shows the point at which ``type-name`` is frozen, with possible
5759 associated actions to be performed at the freeze point.
5762 :samp:`reference {itype}`
5763 Reference (and hence definition) to internal type ``itype``.
5766 :samp:`{function-name}! ({arg}, {arg}, {arg})`
5767 Intrinsic function call.
5770 :samp:`{label-name} : label`
5771 Declaration of label ``labelname``.
5774 :samp:`#$ {subprogram-name}`
5775 An implicit call to a run-time support routine
5776 (to meet the requirement of H.3.1(9) in a
5780 :samp:`{expr} && {expr} && {expr} ... && {expr}`
5781 A multiple concatenation (same effect as ``expr`` & ``expr`` &
5782 ``expr``, but handled more efficiently).
5785 :samp:`[constraint_error]`
5786 Raise the ``Constraint_Error`` exception.
5789 :samp:`{expression}'reference`
5790 A pointer to the result of evaluating {expression}.
5793 :samp:`{target-type}!({source-expression})`
5794 An unchecked conversion of ``source-expression`` to ``target-type``.
5797 :samp:`[{numerator}/{denominator}]`
5798 Used to represent internal real literals (that) have no exact
5799 representation in base 2-16 (for example, the result of compile time
5800 evaluation of the expression 1.0/27.0).
5803 .. index:: -gnatD (gcc)
5805 :switch:`-gnatD[=nn]`
5806 When used in conjunction with :switch:`-gnatG`, this switch causes
5807 the expanded source, as described above for
5808 :switch:`-gnatG` to be written to files with names
5809 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
5810 instead of to the standard output file. For
5811 example, if the source file name is :file:`hello.adb`, then a file
5812 :file:`hello.adb.dg` will be written. The debugging
5813 information generated by the ``gcc`` :switch:`-g` switch
5814 will refer to the generated :file:`xxx.dg` file. This allows
5815 you to do source level debugging using the generated code which is
5816 sometimes useful for complex code, for example to find out exactly
5817 which part of a complex construction raised an exception. This switch
5818 also suppresses generation of cross-reference information (see
5819 :switch:`-gnatx`) since otherwise the cross-reference information
5820 would refer to the :file:`.dg` file, which would cause
5821 confusion since this is not the original source file.
5823 Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
5824 automatically, so it is not necessary to give both options.
5825 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
5827 .. index:: -gnatL (gcc)
5829 If the switch :switch:`-gnatL` is used in conjunction with
5830 :switch:`-gnatDG`, then the original source lines are interspersed
5831 in the expanded source (as comment lines with the original line number).
5833 The optional parameter ``nn`` if present after -gnatD specifies an
5834 alternative maximum line length that overrides the normal default of 72.
5835 This value is in the range 40-999999, values less than 40 being silently
5836 reset to 40. The equal sign is optional.
5839 .. index:: -gnatr (gcc)
5840 .. index:: pragma Restrictions
5843 This switch causes pragma Restrictions to be treated as Restriction_Warnings
5844 so that violation of restrictions causes warnings rather than illegalities.
5845 This is useful during the development process when new restrictions are added
5846 or investigated. The switch also causes pragma Profile to be treated as
5847 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
5848 restriction warnings rather than restrictions.
5851 .. index:: -gnatR (gcc)
5853 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
5854 This switch controls output from the compiler of a listing showing
5855 representation information for declared types, objects and subprograms.
5856 For :switch:`-gnatR0`, no information is output (equivalent to omitting
5857 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
5858 so :switch:`-gnatR` with no parameter has the same effect), size and
5859 alignment information is listed for declared array and record types.
5861 For :switch:`-gnatR2`, size and alignment information is listed for all
5862 declared types and objects. The ``Linker_Section`` is also listed for any
5863 entity for which the ``Linker_Section`` is set explicitly or implicitly (the
5864 latter case occurs for objects of a type for which a ``Linker_Section``
5867 For :switch:`-gnatR3`, symbolic expressions for values that are computed
5868 at run time for records are included. These symbolic expressions have
5869 a mostly obvious format with #n being used to represent the value of the
5870 n'th discriminant. See source files :file:`repinfo.ads/adb` in the
5871 GNAT sources for full details on the format of :switch:`-gnatR3` output.
5873 For :switch:`-gnatR4`, information for relevant compiler-generated types
5874 is also listed, i.e. when they are structurally part of other declared
5877 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
5878 extended representation information for record sub-components of records
5881 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
5882 subprogram conventions and parameter passing mechanisms for all the
5883 subprograms are included.
5885 If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
5886 the output is in the JSON data interchange format specified by the
5887 ECMA-404 standard. The semantic description of this JSON output is
5888 available in the specification of the Repinfo unit present in the
5891 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
5892 the output is to a file with the name :file:`file.rep` where ``file`` is
5893 the name of the corresponding source file, except if ``j`` is also
5894 specified, in which case the file name is :file:`file.json`.
5896 Note that it is possible for record components to have zero size. In
5897 this case, the component clause uses an obvious extension of permitted
5898 Ada syntax, for example ``at 0 range 0 .. -1``.
5901 .. index:: -gnatS (gcc)
5904 The use of the switch :switch:`-gnatS` for an
5905 Ada compilation will cause the compiler to output a
5906 representation of package Standard in a form very
5907 close to standard Ada. It is not quite possible to
5908 do this entirely in standard Ada (since new
5909 numeric base types cannot be created in standard
5910 Ada), but the output is easily
5911 readable to any Ada programmer, and is useful to
5912 determine the characteristics of target dependent
5913 types in package Standard.
5916 .. index:: -gnatx (gcc)
5919 Normally the compiler generates full cross-referencing information in
5920 the :file:`ALI` file. This information is used by a number of tools,
5921 including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch
5922 suppresses this information. This saves some space and may slightly
5923 speed up compilation, but means that these tools cannot be used.
5926 .. index:: -fgnat-encodings (gcc)
5928 :switch:`-fgnat-encodings=[all|gdb|minimal]`
5929 This switch controls the balance between GNAT encodings and standard DWARF
5930 emitted in the debug information.
5932 Historically, old debug formats like stabs were not powerful enough to
5933 express some Ada types (for instance, variant records or fixed-point types).
5934 To work around this, GNAT introduced proprietary encodings that embed the
5935 missing information ("GNAT encodings").
5937 Recent versions of the DWARF debug information format are now able to
5938 correctly describe most of these Ada constructs ("standard DWARF"). As
5939 third-party tools started to use this format, GNAT has been enhanced to
5940 generate it. However, most tools (including GDB) are still relying on GNAT
5943 To support all tools, GNAT needs to be versatile about the balance between
5944 generation of GNAT encodings and standard DWARF. This is what
5945 :switch:`-fgnat-encodings` is about.
5947 * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as
5948 possible so it does not conflict with GNAT encodings.
5949 * ``=gdb``: Emit as much standard DWARF as possible as long as the current
5950 GDB handles it. Emit GNAT encodings for the rest.
5951 * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT
5952 encodings for the rest.
5955 .. _Exception_Handling_Control:
5957 Exception Handling Control
5958 --------------------------
5960 GNAT uses two methods for handling exceptions at run time. The
5961 ``setjmp/longjmp`` method saves the context when entering
5962 a frame with an exception handler. Then when an exception is
5963 raised, the context can be restored immediately, without the
5964 need for tracing stack frames. This method provides very fast
5965 exception propagation, but introduces significant overhead for
5966 the use of exception handlers, even if no exception is raised.
5968 The other approach is called 'zero cost' exception handling.
5969 With this method, the compiler builds static tables to describe
5970 the exception ranges. No dynamic code is required when entering
5971 a frame containing an exception handler. When an exception is
5972 raised, the tables are used to control a back trace of the
5973 subprogram invocation stack to locate the required exception
5974 handler. This method has considerably poorer performance for
5975 the propagation of exceptions, but there is no overhead for
5976 exception handlers if no exception is raised. Note that in this
5977 mode and in the context of mixed Ada and C/C++ programming,
5978 to propagate an exception through a C/C++ code, the C/C++ code
5979 must be compiled with the :switch:`-funwind-tables` GCC's
5982 The following switches may be used to control which of the
5983 two exception handling methods is used.
5987 .. index:: --RTS=sjlj (gnatmake)
5989 :switch:`--RTS=sjlj`
5990 This switch causes the setjmp/longjmp run-time (when available) to be used
5991 for exception handling. If the default
5992 mechanism for the target is zero cost exceptions, then
5993 this switch can be used to modify this default, and must be
5994 used for all units in the partition.
5995 This option is rarely used. One case in which it may be
5996 advantageous is if you have an application where exception
5997 raising is common and the overall performance of the
5998 application is improved by favoring exception propagation.
6001 .. index:: --RTS=zcx (gnatmake)
6002 .. index:: Zero Cost Exceptions
6005 This switch causes the zero cost approach to be used
6006 for exception handling. If this is the default mechanism for the
6007 target (see below), then this switch is unneeded. If the default
6008 mechanism for the target is setjmp/longjmp exceptions, then
6009 this switch can be used to modify this default, and must be
6010 used for all units in the partition.
6011 This option can only be used if the zero cost approach
6012 is available for the target in use, otherwise it will generate an error.
6014 The same option :switch:`--RTS` must be used both for ``gcc``
6015 and ``gnatbind``. Passing this option to ``gnatmake``
6016 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
6017 through the compilation and binding steps.
6019 .. _Units_to_Sources_Mapping_Files:
6021 Units to Sources Mapping Files
6022 ------------------------------
6026 .. index:: -gnatem (gcc)
6028 :switch:`-gnatem={path}`
6029 A mapping file is a way to communicate to the compiler two mappings:
6030 from unit names to file names (without any directory information) and from
6031 file names to path names (with full directory information). These mappings
6032 are used by the compiler to short-circuit the path search.
6034 The use of mapping files is not required for correct operation of the
6035 compiler, but mapping files can improve efficiency, particularly when
6036 sources are read over a slow network connection. In normal operation,
6037 you need not be concerned with the format or use of mapping files,
6038 and the :switch:`-gnatem` switch is not a switch that you would use
6039 explicitly. It is intended primarily for use by automatic tools such as
6040 ``gnatmake`` running under the project file facility. The
6041 description here of the format of mapping files is provided
6042 for completeness and for possible use by other tools.
6044 A mapping file is a sequence of sets of three lines. In each set, the
6045 first line is the unit name, in lower case, with ``%s`` appended
6046 for specs and ``%b`` appended for bodies; the second line is the
6047 file name; and the third line is the path name.
6053 /gnat/project1/sources/main.2.ada
6056 When the switch :switch:`-gnatem` is specified, the compiler will
6057 create in memory the two mappings from the specified file. If there is
6058 any problem (nonexistent file, truncated file or duplicate entries),
6059 no mapping will be created.
6061 Several :switch:`-gnatem` switches may be specified; however, only the
6062 last one on the command line will be taken into account.
6064 When using a project file, ``gnatmake`` creates a temporary
6065 mapping file and communicates it to the compiler using this switch.
6068 .. _Code_Generation_Control:
6070 Code Generation Control
6071 -----------------------
6073 The GCC technology provides a wide range of target dependent
6074 :switch:`-m` switches for controlling
6075 details of code generation with respect to different versions of
6076 architectures. This includes variations in instruction sets (e.g.,
6077 different members of the power pc family), and different requirements
6078 for optimal arrangement of instructions (e.g., different members of
6079 the x86 family). The list of available :switch:`-m` switches may be
6080 found in the GCC documentation.
6082 Use of these :switch:`-m` switches may in some cases result in improved
6085 The GNAT technology is tested and qualified without any
6086 :switch:`-m` switches,
6087 so generally the most reliable approach is to avoid the use of these
6088 switches. However, we generally expect most of these switches to work
6089 successfully with GNAT, and many customers have reported successful
6090 use of these options.
6092 Our general advice is to avoid the use of :switch:`-m` switches unless
6093 special needs lead to requirements in this area. In particular,
6094 there is no point in using :switch:`-m` switches to improve performance
6095 unless you actually see a performance improvement.
6098 .. _Linker_Switches:
6103 Linker switches can be specified after :switch:`-largs` builder switch.
6105 .. index:: -fuse-ld=name
6107 :switch:`-fuse-ld={name}`
6108 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`,
6109 the alternative being ``gold`` for :file:`ld.gold`. The later is
6110 a more recent and faster linker, but only available on GNU/Linux
6113 .. _Binding_with_gnatbind:
6115 Binding with ``gnatbind``
6116 =========================
6118 .. index:: ! gnatbind
6120 This chapter describes the GNAT binder, ``gnatbind``, which is used
6121 to bind compiled GNAT objects.
6123 The ``gnatbind`` program performs four separate functions:
6125 * Checks that a program is consistent, in accordance with the rules in
6126 Chapter 10 of the Ada Reference Manual. In particular, error
6127 messages are generated if a program uses inconsistent versions of a
6130 * Checks that an acceptable order of elaboration exists for the program
6131 and issues an error message if it cannot find an order of elaboration
6132 that satisfies the rules in Chapter 10 of the Ada Language Manual.
6134 * Generates a main program incorporating the given elaboration order.
6135 This program is a small Ada package (body and spec) that
6136 must be subsequently compiled
6137 using the GNAT compiler. The necessary compilation step is usually
6138 performed automatically by ``gnatlink``. The two most important
6139 functions of this program
6140 are to call the elaboration routines of units in an appropriate order
6141 and to call the main program.
6143 * Determines the set of object files required by the given main program.
6144 This information is output in the forms of comments in the generated program,
6145 to be read by the ``gnatlink`` utility used to link the Ada application.
6147 .. _Running_gnatbind:
6149 Running ``gnatbind``
6150 --------------------
6152 The form of the ``gnatbind`` command is
6156 $ gnatbind [ switches ] mainprog[.ali] [ switches ]
6159 where :file:`mainprog.adb` is the Ada file containing the main program
6160 unit body. ``gnatbind`` constructs an Ada
6161 package in two files whose names are
6162 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
6163 For example, if given the
6164 parameter :file:`hello.ali`, for a main program contained in file
6165 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
6166 and :file:`b~hello.adb`.
6168 When doing consistency checking, the binder takes into consideration
6169 any source files it can locate. For example, if the binder determines
6170 that the given main program requires the package ``Pack``, whose
6172 file is :file:`pack.ali` and whose corresponding source spec file is
6173 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
6174 (using the same search path conventions as previously described for the
6175 ``gcc`` command). If it can locate this source file, it checks that
6177 or source checksums of the source and its references to in :file:`ALI` files
6178 match. In other words, any :file:`ALI` files that mentions this spec must have
6179 resulted from compiling this version of the source file (or in the case
6180 where the source checksums match, a version close enough that the
6181 difference does not matter).
6183 .. index:: Source files, use by binder
6185 The effect of this consistency checking, which includes source files, is
6186 that the binder ensures that the program is consistent with the latest
6187 version of the source files that can be located at bind time. Editing a
6188 source file without compiling files that depend on the source file cause
6189 error messages to be generated by the binder.
6191 For example, suppose you have a main program :file:`hello.adb` and a
6192 package ``P``, from file :file:`p.ads` and you perform the following
6195 * Enter ``gcc -c hello.adb`` to compile the main program.
6197 * Enter ``gcc -c p.ads`` to compile package ``P``.
6199 * Edit file :file:`p.ads`.
6201 * Enter ``gnatbind hello``.
6203 At this point, the file :file:`p.ali` contains an out-of-date time stamp
6204 because the file :file:`p.ads` has been edited. The attempt at binding
6205 fails, and the binder generates the following error messages:
6210 error: "hello.adb" must be recompiled ("p.ads" has been modified)
6211 error: "p.ads" has been modified and must be recompiled
6214 Now both files must be recompiled as indicated, and then the bind can
6215 succeed, generating a main program. You need not normally be concerned
6216 with the contents of this file, but for reference purposes a sample
6217 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6219 In most normal usage, the default mode of ``gnatbind`` which is to
6220 generate the main package in Ada, as described in the previous section.
6221 In particular, this means that any Ada programmer can read and understand
6222 the generated main program. It can also be debugged just like any other
6223 Ada code provided the :switch:`-g` switch is used for
6224 ``gnatbind`` and ``gnatlink``.
6226 .. _Switches_for_gnatbind:
6228 Switches for ``gnatbind``
6229 -------------------------
6231 The following switches are available with ``gnatbind``; details will
6232 be presented in subsequent sections.
6235 .. index:: --version (gnatbind)
6238 Display Copyright and version, then exit disregarding all other options.
6241 .. index:: --help (gnatbind)
6244 If :switch:`--version` was not used, display usage, then exit disregarding
6248 .. index:: -a (gnatbind)
6251 Indicates that, if supported by the platform, the adainit procedure should
6252 be treated as an initialisation routine by the linker (a constructor). This
6253 is intended to be used by the Project Manager to automatically initialize
6254 shared Stand-Alone Libraries.
6257 .. index:: -aO (gnatbind)
6260 Specify directory to be searched for ALI files.
6263 .. index:: -aI (gnatbind)
6266 Specify directory to be searched for source file.
6269 .. index:: -A (gnatbind)
6271 :switch:`-A[={filename}]`
6272 Output ALI list (to standard output or to the named file).
6275 .. index:: -b (gnatbind)
6278 Generate brief messages to :file:`stderr` even if verbose mode set.
6281 .. index:: -c (gnatbind)
6284 Check only, no generation of binder output file.
6287 .. index:: -dnn[k|m] (gnatbind)
6289 :switch:`-d{nn}[k|m]`
6290 This switch can be used to change the default task stack size value
6291 to a specified size ``nn``, which is expressed in bytes by default, or
6292 in kilobytes when suffixed with ``k`` or in megabytes when suffixed
6294 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6295 in effect, to completing all task specs with
6299 pragma Storage_Size (nn);
6301 When they do not already have such a pragma.
6304 .. index:: -D (gnatbind)
6306 :switch:`-D{nn}[k|m]`
6307 Set the default secondary stack size to ``nn``. The suffix indicates whether
6308 the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
6311 The secondary stack holds objects of unconstrained types that are returned by
6312 functions, for example unconstrained Strings. The size of the secondary stack
6313 can be dynamic or fixed depending on the target.
6315 For most targets, the secondary stack grows on demand and is implemented as
6316 a chain of blocks in the heap. In this case, the default secondary stack size
6317 determines the initial size of the secondary stack for each task and the
6318 smallest amount the secondary stack can grow by.
6320 For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
6321 fixed. This switch can be used to change the default size of these stacks.
6322 The default secondary stack size can be overridden on a per-task basis if
6323 individual tasks have different secondary stack requirements. This is
6324 achieved through the Secondary_Stack_Size aspect that takes the size of the
6325 secondary stack in bytes.
6327 .. index:: -e (gnatbind)
6330 Output complete list of elaboration-order dependencies.
6333 .. index:: -Ea (gnatbind)
6336 Store tracebacks in exception occurrences when the target supports it.
6337 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6338 unless symbolic tracebacks are enabled.
6340 See also the packages ``GNAT.Traceback`` and
6341 ``GNAT.Traceback.Symbolic`` for more information.
6342 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
6346 .. index:: -Es (gnatbind)
6349 Store tracebacks in exception occurrences when the target supports it.
6350 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6353 .. index:: -E (gnatbind)
6356 Currently the same as ``-Ea``.
6359 .. index:: -f (gnatbind)
6361 :switch:`-f{elab-order}`
6362 Force elaboration order.
6364 .. index:: -F (gnatbind)
6367 Force the checks of elaboration flags. ``gnatbind`` does not normally
6368 generate checks of elaboration flags for the main executable, except when
6369 a Stand-Alone Library is used. However, there are cases when this cannot be
6370 detected by gnatbind. An example is importing an interface of a Stand-Alone
6371 Library through a pragma Import and only specifying through a linker switch
6372 this Stand-Alone Library. This switch is used to guarantee that elaboration
6373 flag checks are generated.
6376 .. index:: -h (gnatbind)
6379 Output usage (help) information.
6382 .. index:: -H32 (gnatbind)
6385 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
6386 For further details see :ref:`Dynamic_Allocation_Control`.
6389 .. index:: -H64 (gnatbind)
6390 .. index:: __gnat_malloc
6393 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
6394 For further details see :ref:`Dynamic_Allocation_Control`.
6397 .. index:: -I (gnatbind)
6400 Specify directory to be searched for source and ALI files.
6403 .. index:: -I- (gnatbind)
6406 Do not look for sources in the current directory where ``gnatbind`` was
6407 invoked, and do not look for ALI files in the directory containing the
6408 ALI file named in the ``gnatbind`` command line.
6411 .. index:: -l (gnatbind)
6414 Output chosen elaboration order.
6417 .. index:: -L (gnatbind)
6420 Bind the units for library building. In this case the ``adainit`` and
6421 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6422 are renamed to :samp:`{xxx}init` and
6425 (:ref:`GNAT_and_Libraries`, for more details.)
6428 .. index:: -M (gnatbind)
6431 Rename generated main program from main to xyz. This option is
6432 supported on cross environments only.
6435 .. index:: -m (gnatbind)
6438 Limit number of detected errors or warnings to ``n``, where ``n`` is
6439 in the range 1..999999. The default value if no switch is
6440 given is 9999. If the number of warnings reaches this limit, then a
6441 message is output and further warnings are suppressed, the bind
6442 continues in this case. If the number of errors reaches this
6443 limit, then a message is output and the bind is abandoned.
6444 A value of zero means that no limit is enforced. The equal
6448 .. index:: -n (gnatbind)
6454 .. index:: -nostdinc (gnatbind)
6457 Do not look for sources in the system default directory.
6460 .. index:: -nostdlib (gnatbind)
6463 Do not look for library files in the system default directory.
6466 .. index:: --RTS (gnatbind)
6468 :switch:`--RTS={rts-path}`
6469 Specifies the default location of the run-time library. Same meaning as the
6470 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
6472 .. index:: -o (gnatbind)
6475 Name the output file ``file`` (default is :file:`b~`xxx`.adb`).
6476 Note that if this option is used, then linking must be done manually,
6477 gnatlink cannot be used.
6480 .. index:: -O (gnatbind)
6482 :switch:`-O[={filename}]`
6483 Output object list (to standard output or to the named file).
6486 .. index:: -p (gnatbind)
6489 Pessimistic (worst-case) elaboration order.
6492 .. index:: -P (gnatbind)
6495 Generate binder file suitable for CodePeer.
6498 .. index:: -R (gnatbind)
6501 Output closure source list, which includes all non-run-time units that are
6502 included in the bind.
6505 .. index:: -Ra (gnatbind)
6508 Like :switch:`-R` but the list includes run-time units.
6511 .. index:: -s (gnatbind)
6514 Require all source files to be present.
6517 .. index:: -S (gnatbind)
6520 Specifies the value to be used when detecting uninitialized scalar
6521 objects with pragma Initialize_Scalars.
6522 The ``xxx`` string specified with the switch is one of:
6524 * ``in`` for an invalid value.
6526 If zero is invalid for the discrete type in question,
6527 then the scalar value is set to all zero bits.
6528 For signed discrete types, the largest possible negative value of
6529 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6530 For unsigned discrete types, the underlying scalar value is set to all
6531 one bits. For floating-point types, a NaN value is set
6532 (see body of package System.Scalar_Values for exact values).
6534 * ``lo`` for low value.
6536 If zero is invalid for the discrete type in question,
6537 then the scalar value is set to all zero bits.
6538 For signed discrete types, the largest possible negative value of
6539 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6540 For unsigned discrete types, the underlying scalar value is set to all
6541 zero bits. For floating-point, a small value is set
6542 (see body of package System.Scalar_Values for exact values).
6544 * ``hi`` for high value.
6546 If zero is invalid for the discrete type in question,
6547 then the scalar value is set to all one bits.
6548 For signed discrete types, the largest possible positive value of
6549 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6550 For unsigned discrete types, the underlying scalar value is set to all
6551 one bits. For floating-point, a large value is set
6552 (see body of package System.Scalar_Values for exact values).
6554 * ``xx`` for hex value (two hex digits).
6556 The underlying scalar is set to a value consisting of repeated bytes, whose
6557 value corresponds to the given value. For example if ``BF`` is given,
6558 then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``.
6560 .. index:: GNAT_INIT_SCALARS
6562 In addition, you can specify :switch:`-Sev` to indicate that the value is
6563 to be set at run time. In this case, the program will look for an environment
6564 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
6565 of :samp:`in/lo/hi/{xx}` with the same meanings as above.
6566 If no environment variable is found, or if it does not have a valid value,
6567 then the default is ``in`` (invalid values).
6569 .. index:: -static (gnatbind)
6572 Link against a static GNAT run-time.
6575 .. index:: -shared (gnatbind)
6578 Link against a shared GNAT run-time when available.
6581 .. index:: -t (gnatbind)
6584 Tolerate time stamp and other consistency errors.
6587 .. index:: -T (gnatbind)
6590 Set the time slice value to ``n`` milliseconds. If the system supports
6591 the specification of a specific time slice value, then the indicated value
6592 is used. If the system does not support specific time slice values, but
6593 does support some general notion of round-robin scheduling, then any
6594 nonzero value will activate round-robin scheduling.
6596 A value of zero is treated specially. It turns off time
6597 slicing, and in addition, indicates to the tasking run-time that the
6598 semantics should match as closely as possible the Annex D
6599 requirements of the Ada RM, and in particular sets the default
6600 scheduling policy to ``FIFO_Within_Priorities``.
6603 .. index:: -u (gnatbind)
6606 Enable dynamic stack usage, with ``n`` results stored and displayed
6607 at program termination. A result is generated when a task
6608 terminates. Results that can't be stored are displayed on the fly, at
6609 task termination. This option is currently not supported on Itanium
6610 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6613 .. index:: -v (gnatbind)
6616 Verbose mode. Write error messages, header, summary output to
6620 .. index:: -V (gnatbind)
6622 :switch:`-V{key}={value}`
6623 Store the given association of ``key`` to ``value`` in the bind environment.
6624 Values stored this way can be retrieved at run time using
6625 ``GNAT.Bind_Environment``.
6628 .. index:: -w (gnatbind)
6631 Warning mode; ``x`` = s/e for suppress/treat as error.
6634 .. index:: -Wx (gnatbind)
6637 Override default wide character encoding for standard Text_IO files.
6640 .. index:: -x (gnatbind)
6643 Exclude source files (check object consistency only).
6646 .. index:: -Xnnn (gnatbind)
6649 Set default exit status value, normally 0 for POSIX compliance.
6652 .. index:: -y (gnatbind)
6655 Enable leap seconds support in ``Ada.Calendar`` and its children.
6658 .. index:: -z (gnatbind)
6663 You may obtain this listing of switches by running ``gnatbind`` with
6667 .. _Consistency-Checking_Modes:
6669 Consistency-Checking Modes
6670 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6672 As described earlier, by default ``gnatbind`` checks
6673 that object files are consistent with one another and are consistent
6674 with any source files it can locate. The following switches control binder
6678 .. index:: -s (gnatbind)
6681 Require source files to be present. In this mode, the binder must be
6682 able to locate all source files that are referenced, in order to check
6683 their consistency. In normal mode, if a source file cannot be located it
6684 is simply ignored. If you specify this switch, a missing source
6688 .. index:: -Wx (gnatbind)
6691 Override default wide character encoding for standard Text_IO files.
6692 Normally the default wide character encoding method used for standard
6693 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6694 the main source input (see description of switch
6695 :switch:`-gnatWx` for the compiler). The
6696 use of this switch for the binder (which has the same set of
6697 possible arguments) overrides this default as specified.
6700 .. index:: -x (gnatbind)
6703 Exclude source files. In this mode, the binder only checks that ALI
6704 files are consistent with one another. Source files are not accessed.
6705 The binder runs faster in this mode, and there is still a guarantee that
6706 the resulting program is self-consistent.
6707 If a source file has been edited since it was last compiled, and you
6708 specify this switch, the binder will not detect that the object
6709 file is out of date with respect to the source file. Note that this is the
6710 mode that is automatically used by ``gnatmake`` because in this
6711 case the checking against sources has already been performed by
6712 ``gnatmake`` in the course of compilation (i.e., before binding).
6715 .. _Binder_Error_Message_Control:
6717 Binder Error Message Control
6718 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6720 The following switches provide control over the generation of error
6721 messages from the binder:
6725 .. index:: -v (gnatbind)
6728 Verbose mode. In the normal mode, brief error messages are generated to
6729 :file:`stderr`. If this switch is present, a header is written
6730 to :file:`stdout` and any error messages are directed to :file:`stdout`.
6731 All that is written to :file:`stderr` is a brief summary message.
6734 .. index:: -b (gnatbind)
6737 Generate brief error messages to :file:`stderr` even if verbose mode is
6738 specified. This is relevant only when used with the
6739 :switch:`-v` switch.
6742 .. index:: -m (gnatbind)
6745 Limits the number of error messages to ``n``, a decimal integer in the
6746 range 1-999. The binder terminates immediately if this limit is reached.
6749 .. index:: -M (gnatbind)
6752 Renames the generated main program from ``main`` to ``xxx``.
6753 This is useful in the case of some cross-building environments, where
6754 the actual main program is separate from the one generated
6758 .. index:: -ws (gnatbind)
6762 Suppress all warning messages.
6765 .. index:: -we (gnatbind)
6768 Treat any warning messages as fatal errors.
6771 .. index:: -t (gnatbind)
6772 .. index:: Time stamp checks, in binder
6773 .. index:: Binder consistency checks
6774 .. index:: Consistency checks, in binder
6777 The binder performs a number of consistency checks including:
6780 * Check that time stamps of a given source unit are consistent
6782 * Check that checksums of a given source unit are consistent
6784 * Check that consistent versions of ``GNAT`` were used for compilation
6786 * Check consistency of configuration pragmas as required
6788 Normally failure of such checks, in accordance with the consistency
6789 requirements of the Ada Reference Manual, causes error messages to be
6790 generated which abort the binder and prevent the output of a binder
6791 file and subsequent link to obtain an executable.
6793 The :switch:`-t` switch converts these error messages
6794 into warnings, so that
6795 binding and linking can continue to completion even in the presence of such
6796 errors. The result may be a failed link (due to missing symbols), or a
6797 non-functional executable which has undefined semantics.
6801 This means that :switch:`-t` should be used only in unusual situations,
6804 .. _Elaboration_Control:
6809 The following switches provide additional control over the elaboration
6810 order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`.
6813 .. index:: -f (gnatbind)
6815 :switch:`-f{elab-order}`
6816 Force elaboration order.
6818 ``elab-order`` should be the name of a "forced elaboration order file", that
6819 is, a text file containing library item names, one per line. A name of the
6820 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
6821 name of the form "some.unit%b" or "some.unit (body)" denotes the body of
6822 Some.Unit. Each pair of lines is taken to mean that there is an elaboration
6823 dependence of the second line on the first. For example, if the file
6833 then the spec of This will be elaborated before the body of This, and the
6834 body of This will be elaborated before the spec of That, and the spec of That
6835 will be elaborated before the body of That. The first and last of these three
6836 dependences are already required by Ada rules, so this file is really just
6837 forcing the body of This to be elaborated before the spec of That.
6839 The given order must be consistent with Ada rules, or else ``gnatbind`` will
6840 give elaboration cycle errors. For example, if you say x (body) should be
6841 elaborated before x (spec), there will be a cycle, because Ada rules require
6842 x (spec) to be elaborated before x (body); you can't have the spec and body
6843 both elaborated before each other.
6845 If you later add "with That;" to the body of This, there will be a cycle, in
6846 which case you should erase either "this (body)" or "that (spec)" from the
6847 above forced elaboration order file.
6849 Blank lines and Ada-style comments are ignored. Unit names that do not exist
6850 in the program are ignored. Units in the GNAT predefined library are also
6854 .. index:: -p (gnatbind)
6857 Normally the binder attempts to choose an elaboration order that is
6858 likely to minimize the likelihood of an elaboration order error resulting
6859 in raising a ``Program_Error`` exception. This switch reverses the
6860 action of the binder, and requests that it deliberately choose an order
6861 that is likely to maximize the likelihood of an elaboration error.
6862 This is useful in ensuring portability and avoiding dependence on
6863 accidental fortuitous elaboration ordering.
6865 Normally it only makes sense to use the :switch:`-p`
6867 elaboration checking is used (:switch:`-gnatE` switch used for compilation).
6868 This is because in the default static elaboration mode, all necessary
6869 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
6870 These implicit pragmas are still respected by the binder in
6871 :switch:`-p` mode, so a
6872 safe elaboration order is assured.
6874 Note that :switch:`-p` is not intended for
6875 production use; it is more for debugging/experimental use.
6882 The following switches allow additional control over the output
6883 generated by the binder.
6886 .. index:: -c (gnatbind)
6889 Check only. Do not generate the binder output file. In this mode the
6890 binder performs all error checks but does not generate an output file.
6893 .. index:: -e (gnatbind)
6896 Output complete list of elaboration-order dependencies, showing the
6897 reason for each dependency. This output can be rather extensive but may
6898 be useful in diagnosing problems with elaboration order. The output is
6899 written to :file:`stdout`.
6902 .. index:: -h (gnatbind)
6905 Output usage information. The output is written to :file:`stdout`.
6908 .. index:: -K (gnatbind)
6911 Output linker options to :file:`stdout`. Includes library search paths,
6912 contents of pragmas Ident and Linker_Options, and libraries added
6916 .. index:: -l (gnatbind)
6919 Output chosen elaboration order. The output is written to :file:`stdout`.
6922 .. index:: -O (gnatbind)
6925 Output full names of all the object files that must be linked to provide
6926 the Ada component of the program. The output is written to :file:`stdout`.
6927 This list includes the files explicitly supplied and referenced by the user
6928 as well as implicitly referenced run-time unit files. The latter are
6929 omitted if the corresponding units reside in shared libraries. The
6930 directory names for the run-time units depend on the system configuration.
6933 .. index:: -o (gnatbind)
6936 Set name of output file to ``file`` instead of the normal
6937 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
6938 binder generated body filename.
6939 Note that if this option is used, then linking must be done manually.
6940 It is not possible to use gnatlink in this case, since it cannot locate
6944 .. index:: -r (gnatbind)
6947 Generate list of ``pragma Restrictions`` that could be applied to
6948 the current unit. This is useful for code audit purposes, and also may
6949 be used to improve code generation in some cases.
6952 .. _Dynamic_Allocation_Control:
6954 Dynamic Allocation Control
6955 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6957 The heap control switches -- :switch:`-H32` and :switch:`-H64` --
6958 determine whether dynamic allocation uses 32-bit or 64-bit memory.
6959 They only affect compiler-generated allocations via ``__gnat_malloc``;
6960 explicit calls to ``malloc`` and related functions from the C
6961 run-time library are unaffected.
6964 Allocate memory on 32-bit heap
6968 Allocate memory on 64-bit heap. This is the default
6969 unless explicitly overridden by a ``'Size`` clause on the access type.
6971 These switches are only effective on VMS platforms.
6974 .. _Binding_with_Non-Ada_Main_Programs:
6976 Binding with Non-Ada Main Programs
6977 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6979 The description so far has assumed that the main
6980 program is in Ada, and that the task of the binder is to generate a
6981 corresponding function ``main`` that invokes this Ada main
6982 program. GNAT also supports the building of executable programs where
6983 the main program is not in Ada, but some of the called routines are
6984 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
6985 The following switch is used in this situation:
6988 .. index:: -n (gnatbind)
6991 No main program. The main program is not in Ada.
6993 In this case, most of the functions of the binder are still required,
6994 but instead of generating a main program, the binder generates a file
6995 containing the following callable routines:
7000 You must call this routine to initialize the Ada part of the program by
7001 calling the necessary elaboration routines. A call to ``adainit`` is
7002 required before the first call to an Ada subprogram.
7004 Note that it is assumed that the basic execution environment must be setup
7005 to be appropriate for Ada execution at the point where the first Ada
7006 subprogram is called. In particular, if the Ada code will do any
7007 floating-point operations, then the FPU must be setup in an appropriate
7008 manner. For the case of the x86, for example, full precision mode is
7009 required. The procedure GNAT.Float_Control.Reset may be used to ensure
7010 that the FPU is in the right state.
7015 You must call this routine to perform any library-level finalization
7016 required by the Ada subprograms. A call to ``adafinal`` is required
7017 after the last call to an Ada subprogram, and before the program
7020 .. index:: -n (gnatbind)
7021 .. index:: Binder, multiple input files
7023 If the :switch:`-n` switch
7024 is given, more than one ALI file may appear on
7025 the command line for ``gnatbind``. The normal ``closure``
7026 calculation is performed for each of the specified units. Calculating
7027 the closure means finding out the set of units involved by tracing
7028 |with| references. The reason it is necessary to be able to
7029 specify more than one ALI file is that a given program may invoke two or
7030 more quite separate groups of Ada units.
7032 The binder takes the name of its output file from the last specified ALI
7033 file, unless overridden by the use of the :switch:`-o file`.
7035 .. index:: -o (gnatbind)
7037 The output is an Ada unit in source form that can be compiled with GNAT.
7038 This compilation occurs automatically as part of the ``gnatlink``
7041 Currently the GNAT run-time requires a FPU using 80 bits mode
7042 precision. Under targets where this is not the default it is required to
7043 call GNAT.Float_Control.Reset before using floating point numbers (this
7044 include float computation, float input and output) in the Ada code. A
7045 side effect is that this could be the wrong mode for the foreign code
7046 where floating point computation could be broken after this call.
7049 .. _Binding_Programs_with_No_Main_Subprogram:
7051 Binding Programs with No Main Subprogram
7052 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7054 It is possible to have an Ada program which does not have a main
7055 subprogram. This program will call the elaboration routines of all the
7056 packages, then the finalization routines.
7058 The following switch is used to bind programs organized in this manner:
7060 .. index:: -z (gnatbind)
7063 Normally the binder checks that the unit name given on the command line
7064 corresponds to a suitable main subprogram. When this switch is used,
7065 a list of ALI files can be given, and the execution of the program
7066 consists of elaboration of these units in an appropriate order. Note
7067 that the default wide character encoding method for standard Text_IO
7068 files is always set to Brackets if this switch is set (you can use
7070 :switch:`-Wx` to override this default).
7073 .. _Command-Line_Access:
7078 The package ``Ada.Command_Line`` provides access to the command-line
7079 arguments and program name. In order for this interface to operate
7080 correctly, the two variables
7087 .. index:: gnat_argv
7088 .. index:: gnat_argc
7090 are declared in one of the GNAT library routines. These variables must
7091 be set from the actual ``argc`` and ``argv`` values passed to the
7092 main program. With no *n* present, ``gnatbind``
7093 generates the C main program to automatically set these variables.
7094 If the *n* switch is used, there is no automatic way to
7095 set these variables. If they are not set, the procedures in
7096 ``Ada.Command_Line`` will not be available, and any attempt to use
7097 them will raise ``Constraint_Error``. If command line access is
7098 required, your main program must set ``gnat_argc`` and
7099 ``gnat_argv`` from the ``argc`` and ``argv`` values passed to
7103 .. _Search_Paths_for_gnatbind:
7105 Search Paths for ``gnatbind``
7106 -----------------------------
7108 The binder takes the name of an ALI file as its argument and needs to
7109 locate source files as well as other ALI files to verify object consistency.
7111 For source files, it follows exactly the same search rules as ``gcc``
7112 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
7113 directories searched are:
7115 * The directory containing the ALI file named in the command line, unless
7116 the switch :switch:`-I-` is specified.
7118 * All directories specified by :switch:`-I`
7119 switches on the ``gnatbind``
7120 command line, in the order given.
7122 .. index:: ADA_PRJ_OBJECTS_FILE
7124 * Each of the directories listed in the text file whose name is given
7125 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
7127 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
7128 driver when project files are used. It should not normally be set
7131 .. index:: ADA_OBJECTS_PATH
7133 * Each of the directories listed in the value of the
7134 :envvar:`ADA_OBJECTS_PATH` environment variable.
7135 Construct this value
7136 exactly as the :envvar:`PATH` environment variable: a list of directory
7137 names separated by colons (semicolons when working with the NT version
7140 * The content of the :file:`ada_object_path` file which is part of the GNAT
7141 installation tree and is used to store standard libraries such as the
7142 GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
7143 specified. See :ref:`Installing_a_library`
7145 .. index:: -I (gnatbind)
7146 .. index:: -aI (gnatbind)
7147 .. index:: -aO (gnatbind)
7149 In the binder the switch :switch:`-I`
7150 is used to specify both source and
7151 library file paths. Use :switch:`-aI`
7152 instead if you want to specify
7153 source paths only, and :switch:`-aO`
7154 if you want to specify library paths
7155 only. This means that for the binder
7156 :switch:`-I{dir}` is equivalent to
7158 :switch:`-aO`{dir}`.
7159 The binder generates the bind file (a C language source file) in the
7160 current working directory.
7164 .. index:: Interfaces
7167 The packages ``Ada``, ``System``, and ``Interfaces`` and their
7168 children make up the GNAT Run-Time Library, together with the package
7169 GNAT and its children, which contain a set of useful additional
7170 library functions provided by GNAT. The sources for these units are
7171 needed by the compiler and are kept together in one directory. The ALI
7172 files and object files generated by compiling the RTL are needed by the
7173 binder and the linker and are kept together in one directory, typically
7174 different from the directory containing the sources. In a normal
7175 installation, you need not specify these directory names when compiling
7176 or binding. Either the environment variables or the built-in defaults
7177 cause these files to be found.
7179 Besides simplifying access to the RTL, a major use of search paths is
7180 in compiling sources from multiple directories. This can make
7181 development environments much more flexible.
7184 .. _Examples_of_gnatbind_Usage:
7186 Examples of ``gnatbind`` Usage
7187 ------------------------------
7189 Here are some examples of ``gnatbind`` invovations:
7195 The main program ``Hello`` (source program in :file:`hello.adb`) is
7196 bound using the standard switch settings. The generated main program is
7197 :file:`b~hello.adb`. This is the normal, default use of the binder.
7201 gnatbind hello -o mainprog.adb
7203 The main program ``Hello`` (source program in :file:`hello.adb`) is
7204 bound using the standard switch settings. The generated main program is
7205 :file:`mainprog.adb` with the associated spec in
7206 :file:`mainprog.ads`. Note that you must specify the body here not the
7207 spec. Note that if this option is used, then linking must be done manually,
7208 since gnatlink will not be able to find the generated file.
7211 .. _Linking_with_gnatlink:
7213 Linking with ``gnatlink``
7214 =========================
7216 .. index:: ! gnatlink
7218 This chapter discusses ``gnatlink``, a tool that links
7219 an Ada program and builds an executable file. This utility
7220 invokes the system linker (via the ``gcc`` command)
7221 with a correct list of object files and library references.
7222 ``gnatlink`` automatically determines the list of files and
7223 references for the Ada part of a program. It uses the binder file
7224 generated by the ``gnatbind`` to determine this list.
7226 .. _Running_gnatlink:
7228 Running ``gnatlink``
7229 --------------------
7231 The form of the ``gnatlink`` command is
7236 $ gnatlink [ switches ] mainprog [.ali]
7237 [ non-Ada objects ] [ linker options ]
7241 The arguments of ``gnatlink`` (switches, main ``ALI`` file,
7243 or linker options) may be in any order, provided that no non-Ada object may
7244 be mistaken for a main :file:`ALI` file.
7245 Any file name :file:`F` without the :file:`.ali`
7246 extension will be taken as the main :file:`ALI` file if a file exists
7247 whose name is the concatenation of :file:`F` and :file:`.ali`.
7249 :file:`mainprog.ali` references the ALI file of the main program.
7250 The :file:`.ali` extension of this file can be omitted. From this
7251 reference, ``gnatlink`` locates the corresponding binder file
7252 :file:`b~mainprog.adb` and, using the information in this file along
7253 with the list of non-Ada objects and linker options, constructs a
7254 linker command file to create the executable.
7256 The arguments other than the ``gnatlink`` switches and the main
7257 :file:`ALI` file are passed to the linker uninterpreted.
7258 They typically include the names of
7259 object files for units written in other languages than Ada and any library
7260 references required to resolve references in any of these foreign language
7261 units, or in ``Import`` pragmas in any Ada units.
7263 ``linker options`` is an optional list of linker specific
7265 The default linker called by gnatlink is ``gcc`` which in
7266 turn calls the appropriate system linker.
7268 One useful option for the linker is :switch:`-s`: it reduces the size of the
7269 executable by removing all symbol table and relocation information from the
7272 Standard options for the linker such as :switch:`-lmy_lib` or
7273 :switch:`-Ldir` can be added as is.
7274 For options that are not recognized by
7275 ``gcc`` as linker options, use the ``gcc`` switches
7276 :switch:`-Xlinker` or :switch:`-Wl,`.
7278 Refer to the GCC documentation for
7281 Here is an example showing how to generate a linker map:
7285 $ gnatlink my_prog -Wl,-Map,MAPFILE
7288 Using ``linker options`` it is possible to set the program stack and
7290 See :ref:`Setting_Stack_Size_from_gnatlink` and
7291 :ref:`Setting_Heap_Size_from_gnatlink`.
7293 ``gnatlink`` determines the list of objects required by the Ada
7294 program and prepends them to the list of objects passed to the linker.
7295 ``gnatlink`` also gathers any arguments set by the use of
7296 ``pragma Linker_Options`` and adds them to the list of arguments
7297 presented to the linker.
7300 .. _Switches_for_gnatlink:
7302 Switches for ``gnatlink``
7303 -------------------------
7305 The following switches are available with the ``gnatlink`` utility:
7307 .. index:: --version (gnatlink)
7310 Display Copyright and version, then exit disregarding all other options.
7313 .. index:: --help (gnatlink)
7316 If :switch:`--version` was not used, display usage, then exit disregarding
7320 .. index:: Command line length
7321 .. index:: -f (gnatlink)
7324 On some targets, the command line length is limited, and ``gnatlink``
7325 will generate a separate file for the linker if the list of object files
7327 The :switch:`-f` switch forces this file
7328 to be generated even if
7329 the limit is not exceeded. This is useful in some cases to deal with
7330 special situations where the command line length is exceeded.
7333 .. index:: Debugging information, including
7334 .. index:: -g (gnatlink)
7337 The option to include debugging information causes the Ada bind file (in
7338 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
7339 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7340 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7341 Without :switch:`-g`, the binder removes these files by default.
7343 .. index:: -n (gnatlink)
7346 Do not compile the file generated by the binder. This may be used when
7347 a link is rerun with different options, but there is no need to recompile
7351 .. index:: -v (gnatlink)
7354 Verbose mode. Causes additional information to be output, including a full
7355 list of the included object files.
7356 This switch option is most useful when you want
7357 to see what set of object files are being used in the link step.
7360 .. index:: -v -v (gnatlink)
7363 Very verbose mode. Requests that the compiler operate in verbose mode when
7364 it compiles the binder file, and that the system linker run in verbose mode.
7367 .. index:: -o (gnatlink)
7369 :switch:`-o {exec-name}`
7370 ``exec-name`` specifies an alternate name for the generated
7371 executable program. If this switch is omitted, the executable has the same
7372 name as the main unit. For example, ``gnatlink try.ali`` creates
7373 an executable called :file:`try`.
7376 .. index:: -B (gnatlink)
7379 Load compiler executables (for example, ``gnat1``, the Ada compiler)
7380 from ``dir`` instead of the default location. Only use this switch
7381 when multiple versions of the GNAT compiler are available.
7382 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
7383 for further details. You would normally use the :switch:`-b` or
7384 :switch:`-V` switch instead.
7387 .. index:: -M (gnatlink)
7390 When linking an executable, create a map file. The name of the map file
7391 has the same name as the executable with extension ".map".
7394 .. index:: -M= (gnatlink)
7396 :switch:`-M={mapfile}`
7397 When linking an executable, create a map file. The name of the map file is
7401 .. index:: --GCC=compiler_name (gnatlink)
7403 :switch:`--GCC={compiler_name}`
7404 Program used for compiling the binder file. The default is
7405 ``gcc``. You need to use quotes around ``compiler_name`` if
7406 ``compiler_name`` contains spaces or other separator characters.
7407 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
7408 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7409 inserted after your command name. Thus in the above example the compiler
7410 command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
7411 A limitation of this syntax is that the name and path name of the executable
7412 itself must not include any embedded spaces. If the compiler executable is
7413 different from the default one (gcc or <prefix>-gcc), then the back-end
7414 switches in the ALI file are not used to compile the binder generated source.
7415 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7416 switches will be used for ``--GCC="gcc -gnatv"``. If several
7417 ``--GCC=compiler_name`` are used, only the last ``compiler_name``
7418 is taken into account. However, all the additional switches are also taken
7420 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7421 ``--GCC="bar -x -y -z -t"``.
7424 .. index:: --LINK= (gnatlink)
7426 :switch:`--LINK={name}`
7427 ``name`` is the name of the linker to be invoked. This is especially
7428 useful in mixed language programs since languages such as C++ require
7429 their own linker to be used. When this switch is omitted, the default
7430 name for the linker is ``gcc``. When this switch is used, the
7431 specified linker is called instead of ``gcc`` with exactly the same
7432 parameters that would have been passed to ``gcc`` so if the desired
7433 linker requires different parameters it is necessary to use a wrapper
7434 script that massages the parameters before invoking the real linker. It
7435 may be useful to control the exact invocation by using the verbose
7439 .. _Using_the_GNU_make_Utility:
7441 Using the GNU ``make`` Utility
7442 ==============================
7444 .. index:: make (GNU), GNU make
7446 This chapter offers some examples of makefiles that solve specific
7447 problems. It does not explain how to write a makefile, nor does it try to replace the
7448 ``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7450 All the examples in this section are specific to the GNU version of
7451 make. Although ``make`` is a standard utility, and the basic language
7452 is the same, these examples use some advanced features found only in
7455 .. _Using_gnatmake_in_a_Makefile:
7457 Using gnatmake in a Makefile
7458 ----------------------------
7460 .. index makefile (GNU make)
7462 Complex project organizations can be handled in a very powerful way by
7463 using GNU make combined with gnatmake. For instance, here is a Makefile
7464 which allows you to build each subsystem of a big project into a separate
7465 shared library. Such a makefile allows you to significantly reduce the link
7466 time of very big applications while maintaining full coherence at
7467 each step of the build process.
7469 The list of dependencies are handled automatically by
7470 ``gnatmake``. The Makefile is simply used to call gnatmake in each of
7471 the appropriate directories.
7473 Note that you should also read the example on how to automatically
7474 create the list of directories
7475 (:ref:`Automatically_Creating_a_List_of_Directories`)
7476 which might help you in case your project has a lot of subdirectories.
7479 .. code-block:: makefile
7481 ## This Makefile is intended to be used with the following directory
7483 ## - The sources are split into a series of csc (computer software components)
7484 ## Each of these csc is put in its own directory.
7485 ## Their name are referenced by the directory names.
7486 ## They will be compiled into shared library (although this would also work
7487 ## with static libraries
7488 ## - The main program (and possibly other packages that do not belong to any
7489 ## csc is put in the top level directory (where the Makefile is).
7490 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7491 ## \\_ second_csc (sources) __ lib (will contain the library)
7493 ## Although this Makefile is build for shared library, it is easy to modify
7494 ## to build partial link objects instead (modify the lines with -shared and
7497 ## With this makefile, you can change any file in the system or add any new
7498 ## file, and everything will be recompiled correctly (only the relevant shared
7499 ## objects will be recompiled, and the main program will be re-linked).
7501 # The list of computer software component for your project. This might be
7502 # generated automatically.
7505 # Name of the main program (no extension)
7508 # If we need to build objects with -fPIC, uncomment the following line
7511 # The following variable should give the directory containing libgnat.so
7512 # You can get this directory through 'gnatls -v'. This is usually the last
7513 # directory in the Object_Path.
7516 # The directories for the libraries
7517 # (This macro expands the list of CSC to the list of shared libraries, you
7518 # could simply use the expanded form:
7519 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7520 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7522 ${MAIN}: objects ${LIB_DIR}
7523 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7524 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7527 # recompile the sources
7528 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7530 # Note: In a future version of GNAT, the following commands will be simplified
7531 # by a new tool, gnatmlib
7534 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7535 cd ${dir $@ } && cp -f ../*.ali .
7537 # The dependencies for the modules
7538 # Note that we have to force the expansion of *.o, since in some cases
7539 # make won't be able to do it itself.
7540 aa/lib/libaa.so: ${wildcard aa/*.o}
7541 bb/lib/libbb.so: ${wildcard bb/*.o}
7542 cc/lib/libcc.so: ${wildcard cc/*.o}
7544 # Make sure all of the shared libraries are in the path before starting the
7547 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7550 ${RM} -rf ${CSC_LIST:%=%/lib}
7551 ${RM} ${CSC_LIST:%=%/*.ali}
7552 ${RM} ${CSC_LIST:%=%/*.o}
7553 ${RM} *.o *.ali ${MAIN}
7556 .. _Automatically_Creating_a_List_of_Directories:
7558 Automatically Creating a List of Directories
7559 --------------------------------------------
7561 In most makefiles, you will have to specify a list of directories, and
7562 store it in a variable. For small projects, it is often easier to
7563 specify each of them by hand, since you then have full control over what
7564 is the proper order for these directories, which ones should be
7567 However, in larger projects, which might involve hundreds of
7568 subdirectories, it might be more convenient to generate this list
7571 The example below presents two methods. The first one, although less
7572 general, gives you more control over the list. It involves wildcard
7573 characters, that are automatically expanded by ``make``. Its
7574 shortcoming is that you need to explicitly specify some of the
7575 organization of your project, such as for instance the directory tree
7576 depth, whether some directories are found in a separate tree, etc.
7578 The second method is the most general one. It requires an external
7579 program, called ``find``, which is standard on all Unix systems. All
7580 the directories found under a given root directory will be added to the
7583 .. code-block:: makefile
7585 # The examples below are based on the following directory hierarchy:
7586 # All the directories can contain any number of files
7587 # ROOT_DIRECTORY -> a -> aa -> aaa
7593 # This Makefile creates a variable called DIRS, that can be reused any time
7594 # you need this list (see the other examples in this section)
7596 # The root of your project's directory hierarchy
7600 # First method: specify explicitly the list of directories
7601 # This allows you to specify any subset of all the directories you need.
7604 DIRS := a/aa/ a/ab/ b/ba/
7607 # Second method: use wildcards
7608 # Note that the argument(s) to wildcard below should end with a '/'.
7609 # Since wildcards also return file names, we have to filter them out
7610 # to avoid duplicate directory names.
7611 # We thus use make's ``dir`` and ``sort`` functions.
7612 # It sets DIRs to the following value (note that the directories aaa and baa
7613 # are not given, unless you change the arguments to wildcard).
7614 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7617 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7618 ${ROOT_DIRECTORY}/*/*/}}}
7621 # Third method: use an external program
7622 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7623 # This is the most complete command: it sets DIRs to the following value:
7624 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7627 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7631 .. _Generating_the_Command_Line_Switches:
7633 Generating the Command Line Switches
7634 ------------------------------------
7636 Once you have created the list of directories as explained in the
7637 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7638 you can easily generate the command line arguments to pass to gnatmake.
7640 For the sake of completeness, this example assumes that the source path
7641 is not the same as the object path, and that you have two separate lists
7644 .. code-block:: makefile
7646 # see "Automatically creating a list of directories" to create
7651 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7652 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7655 gnatmake ${GNATMAKE_SWITCHES} main_unit
7658 .. _Overcoming_Command_Line_Length_Limits:
7660 Overcoming Command Line Length Limits
7661 -------------------------------------
7663 One problem that might be encountered on big projects is that many
7664 operating systems limit the length of the command line. It is thus hard to give
7665 gnatmake the list of source and object directories.
7667 This example shows how you can set up environment variables, which will
7668 make ``gnatmake`` behave exactly as if the directories had been
7669 specified on the command line, but have a much higher length limit (or
7670 even none on most systems).
7672 It assumes that you have created a list of directories in your Makefile,
7673 using one of the methods presented in
7674 :ref:`Automatically_Creating_a_List_of_Directories`.
7675 For the sake of completeness, we assume that the object
7676 path (where the ALI files are found) is different from the sources patch.
7678 Note a small trick in the Makefile below: for efficiency reasons, we
7679 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7680 expanded immediately by ``make``. This way we overcome the standard
7681 make behavior which is to expand the variables only when they are
7684 On Windows, if you are using the standard Windows command shell, you must
7685 replace colons with semicolons in the assignments to these variables.
7687 .. code-block:: makefile
7689 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7690 # This is the same thing as putting the -I arguments on the command line.
7691 # (the equivalent of using -aI on the command line would be to define
7692 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
7693 # You can of course have different values for these variables.
7695 # Note also that we need to keep the previous values of these variables, since
7696 # they might have been set before running 'make' to specify where the GNAT
7697 # library is installed.
7699 # see "Automatically creating a list of directories" to create these
7705 space:=${empty} ${empty}
7706 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
7707 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
7708 ADA_INCLUDE_PATH += ${SOURCE_LIST}
7709 ADA_OBJECTS_PATH += ${OBJECT_LIST}
7710 export ADA_INCLUDE_PATH
7711 export ADA_OBJECTS_PATH