1 .. |with| replace:: *with*
2 .. |withs| replace:: *with*\ s
3 .. |withed| replace:: *with*\ ed
4 .. |withing| replace:: *with*\ ing
6 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
10 .. _Building_Executable_Programs_With_GNAT:
12 **************************************
13 Building Executable Programs with GNAT
14 **************************************
16 This chapter describes first the gnatmake tool
17 (:ref:`The_GNAT_Make_Program_gnatmake`),
18 which automatically determines the set of sources
19 needed by an Ada compilation unit and executes the necessary
20 (re)compilations, binding and linking.
21 It also explains how to use each tool individually: the
22 compiler (gcc, see :ref:`Compiling_with_gcc`),
23 binder (gnatbind, see :ref:`Binding_with_gnatbind`),
24 and linker (gnatlink, see :ref:`Linking_with_gnatlink`)
25 to build executable programs.
26 Finally, this chapter provides examples of
27 how to make use of the general GNU make mechanism
28 in a GNAT context (see :ref:`Using_the_GNU_make_Utility`).
32 For building large systems with components possibly written
33 in different languages (such as Ada, C, C++ and Fortran)
34 and organized into subsystems and libraries, the GPRbuild
35 tool can be used. This tool, and the Project Manager
36 facility that it is based upon, is described in
37 *GPRbuild and GPR Companion Tools User's Guide*.
40 .. _The_GNAT_Make_Program_gnatmake:
42 Building with ``gnatmake``
43 ==========================
47 A typical development cycle when working on an Ada program consists of
50 #. Edit some sources to fix bugs;
54 #. Compile all sources affected;
56 #. Rebind and relink; and
60 .. index:: Dependency rules (compilation)
62 The third step in particular can be tricky, because not only do the modified
63 files have to be compiled, but any files depending on these files must also be
64 recompiled. The dependency rules in Ada can be quite complex, especially
65 in the presence of overloading, ``use`` clauses, generics and inlined
68 ``gnatmake`` automatically takes care of the third and fourth steps
69 of this process. It determines which sources need to be compiled,
70 compiles them, and binds and links the resulting object files.
72 Unlike some other Ada make programs, the dependencies are always
73 accurately recomputed from the new sources. The source based approach of
74 the GNAT compilation model makes this possible. This means that if
75 changes to the source program cause corresponding changes in
76 dependencies, they will always be tracked exactly correctly by
79 Note that for advanced forms of project structure, we recommend creating
80 a project file as explained in the *GNAT_Project_Manager* chapter in the
81 *GPRbuild User's Guide*, and using the
82 ``gprbuild`` tool which supports building with project files and works similarly
90 The usual form of the ``gnatmake`` command is
94 $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
96 The only required argument is one ``file_name``, which specifies
97 a compilation unit that is a main program. Several ``file_names`` can be
98 specified: this will result in several executables being built.
99 If ``switches`` are present, they can be placed before the first
100 ``file_name``, between ``file_names`` or after the last ``file_name``.
101 If ``mode_switches`` are present, they must always be placed after
102 the last ``file_name`` and all ``switches``.
104 If you are using standard file extensions (:file:`.adb` and
105 :file:`.ads`), then the
106 extension may be omitted from the ``file_name`` arguments. However, if
107 you are using non-standard extensions, then it is required that the
108 extension be given. A relative or absolute directory path can be
109 specified in a ``file_name``, in which case, the input source file will
110 be searched for in the specified directory only. Otherwise, the input
111 source file will first be searched in the directory where
112 ``gnatmake`` was invoked and if it is not found, it will be search on
113 the source path of the compiler as described in
114 :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
116 All ``gnatmake`` output (except when you specify :switch:`-M`) is sent to
117 :file:`stderr`. The output produced by the
118 :switch:`-M` switch is sent to :file:`stdout`.
121 .. _Switches_for_gnatmake:
123 Switches for ``gnatmake``
124 -------------------------
126 You may specify any of the following switches to ``gnatmake``:
129 .. index:: --version (gnatmake)
132 Display Copyright and version, then exit disregarding all other options.
135 .. index:: --help (gnatmake)
138 If ``--version`` was not used, display usage, then exit disregarding
142 .. index:: --GCC=compiler_name (gnatmake)
144 :switch:`--GCC={compiler_name}`
145 Program used for compiling. The default is ``gcc``. You need to use
146 quotes around ``compiler_name`` if ``compiler_name`` contains
147 spaces or other separator characters.
148 As an example ``--GCC="foo -x -y"``
149 will instruct ``gnatmake`` to use ``foo -x -y`` as your
150 compiler. A limitation of this syntax is that the name and path name of
151 the executable itself must not include any embedded spaces. Note that
152 switch :switch:`-c` is always inserted after your command name. Thus in the
153 above example the compiler command that will be used by ``gnatmake``
154 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
155 used, only the last ``compiler_name`` is taken into account. However,
156 all the additional switches are also taken into account. Thus,
157 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
158 ``--GCC="bar -x -y -z -t"``.
161 .. index:: --GNATBIND=binder_name (gnatmake)
163 :switch:`--GNATBIND={binder_name}`
164 Program used for binding. The default is ``gnatbind``. You need to
165 use quotes around ``binder_name`` if ``binder_name`` contains spaces
166 or other separator characters.
167 As an example ``--GNATBIND="bar -x -y"``
168 will instruct ``gnatmake`` to use ``bar -x -y`` as your
169 binder. Binder switches that are normally appended by ``gnatmake``
170 to ``gnatbind`` are now appended to the end of ``bar -x -y``.
171 A limitation of this syntax is that the name and path name of the executable
172 itself must not include any embedded spaces.
174 .. index:: --GNATLINK=linker_name (gnatmake)
176 :switch:`--GNATLINK={linker_name}`
177 Program used for linking. The default is ``gnatlink``. You need to
178 use quotes around ``linker_name`` if ``linker_name`` contains spaces
179 or other separator characters.
180 As an example ``--GNATLINK="lan -x -y"``
181 will instruct ``gnatmake`` to use ``lan -x -y`` as your
182 linker. Linker switches that are normally appended by ``gnatmake`` to
183 ``gnatlink`` are now appended to the end of ``lan -x -y``.
184 A limitation of this syntax is that the name and path name of the executable
185 itself must not include any embedded spaces.
187 :switch:`--create-map-file`
188 When linking an executable, create a map file. The name of the map file
189 has the same name as the executable with extension ".map".
191 :switch:`--create-map-file={mapfile}`
192 When linking an executable, create a map file with the specified name.
194 .. index:: --create-missing-dirs (gnatmake)
196 :switch:`--create-missing-dirs`
197 When using project files (:switch:`-P{project}`), automatically create
198 missing object directories, library directories and exec
201 :switch:`--single-compile-per-obj-dir`
202 Disallow simultaneous compilations in the same object directory when
203 project files are used.
205 :switch:`--subdirs={subdir}`
206 Actual object directory of each project file is the subdirectory subdir of the
207 object directory specified or defaulted in the project file.
209 :switch:`--unchecked-shared-lib-imports`
210 By default, shared library projects are not allowed to import static library
211 projects. When this switch is used on the command line, this restriction is
214 :switch:`--source-info={source info file}`
215 Specify a source info file. This switch is active only when project files
216 are used. If the source info file is specified as a relative path, then it is
217 relative to the object directory of the main project. If the source info file
218 does not exist, then after the Project Manager has successfully parsed and
219 processed the project files and found the sources, it creates the source info
220 file. If the source info file already exists and can be read successfully,
221 then the Project Manager will get all the needed information about the sources
222 from the source info file and will not look for them. This reduces the time
223 to process the project files, especially when looking for sources that take a
224 long time. If the source info file exists but cannot be parsed successfully,
225 the Project Manager will attempt to recreate it. If the Project Manager fails
226 to create the source info file, a message is issued, but gnatmake does not
227 fail. ``gnatmake`` "trusts" the source info file. This means that
228 if the source files have changed (addition, deletion, moving to a different
229 source directory), then the source info file need to be deleted and recreated.
232 .. index:: -a (gnatmake)
235 Consider all files in the make process, even the GNAT internal system
236 files (for example, the predefined Ada library files), as well as any
237 locked files. Locked files are files whose ALI file is write-protected.
239 ``gnatmake`` does not check these files,
240 because the assumption is that the GNAT internal files are properly up
241 to date, and also that any write protected ALI files have been properly
242 installed. Note that if there is an installation problem, such that one
243 of these files is not up to date, it will be properly caught by the
245 You may have to specify this switch if you are working on GNAT
246 itself. The switch ``-a`` is also useful
247 in conjunction with ``-f``
248 if you need to recompile an entire application,
249 including run-time files, using special configuration pragmas,
250 such as a ``Normalize_Scalars`` pragma.
253 ``gnatmake -a`` compiles all GNAT
255 ``gcc -c -gnatpg`` rather than ``gcc -c``.
258 .. index:: -b (gnatmake)
261 Bind only. Can be combined with :switch:`-c` to do
262 compilation and binding, but no link.
263 Can be combined with :switch:`-l`
264 to do binding and linking. When not combined with
266 all the units in the closure of the main program must have been previously
267 compiled and must be up to date. The root unit specified by ``file_name``
268 may be given without extension, with the source extension or, if no GNAT
269 Project File is specified, with the ALI file extension.
272 .. index:: -c (gnatmake)
275 Compile only. Do not perform binding, except when :switch:`-b`
276 is also specified. Do not perform linking, except if both
278 :switch:`-l` are also specified.
279 If the root unit specified by ``file_name`` is not a main unit, this is the
280 default. Otherwise ``gnatmake`` will attempt binding and linking
281 unless all objects are up to date and the executable is more recent than
285 .. index:: -C (gnatmake)
288 Use a temporary mapping file. A mapping file is a way to communicate
289 to the compiler two mappings: from unit names to file names (without
290 any directory information) and from file names to path names (with
291 full directory information). A mapping file can make the compiler's
292 file searches faster, especially if there are many source directories,
293 or the sources are read over a slow network connection. If
294 :switch:`-P` is used, a mapping file is always used, so
295 :switch:`-C` is unnecessary; in this case the mapping file
296 is initially populated based on the project file. If
297 :switch:`-C` is used without
299 the mapping file is initially empty. Each invocation of the compiler
300 will add any newly accessed sources to the mapping file.
303 .. index:: -C= (gnatmake)
306 Use a specific mapping file. The file, specified as a path name (absolute or
307 relative) by this switch, should already exist, otherwise the switch is
308 ineffective. The specified mapping file will be communicated to the compiler.
309 This switch is not compatible with a project file
310 (-P`file`) or with multiple compiling processes
311 (-jnnn, when nnn is greater than 1).
314 .. index:: -d (gnatmake)
317 Display progress for each source, up to date or not, as a single line:
321 completed x out of y (zz%)
323 If the file needs to be compiled this is displayed after the invocation of
324 the compiler. These lines are displayed even in quiet output mode.
327 .. index:: -D (gnatmake)
330 Put all object files and ALI file in directory ``dir``.
331 If the :switch:`-D` switch is not used, all object files
332 and ALI files go in the current working directory.
334 This switch cannot be used when using a project file.
337 .. index:: -eI (gnatmake)
340 Indicates that the main source is a multi-unit source and the rank of the unit
341 in the source file is nnn. nnn needs to be a positive number and a valid
342 index in the source. This switch cannot be used when ``gnatmake`` is
343 invoked for several mains.
346 .. index:: -eL (gnatmake)
347 .. index:: symbolic links
350 Follow all symbolic links when processing project files.
351 This should be used if your project uses symbolic links for files or
352 directories, but is not needed in other cases.
354 .. index:: naming scheme
356 This also assumes that no directory matches the naming scheme for files (for
357 instance that you do not have a directory called "sources.ads" when using the
358 default GNAT naming scheme).
360 When you do not have to use this switch (i.e., by default), gnatmake is able to
361 save a lot of system calls (several per source file and object file), which
362 can result in a significant speed up to load and manipulate a project file,
363 especially when using source files from a remote system.
366 .. index:: -eS (gnatmake)
369 Output the commands for the compiler, the binder and the linker
371 instead of standard error.
374 .. index:: -f (gnatmake)
377 Force recompilations. Recompile all sources, even though some object
378 files may be up to date, but don't recompile predefined or GNAT internal
379 files or locked files (files with a write-protected ALI file),
380 unless the :switch:`-a` switch is also specified.
383 .. index:: -F (gnatmake)
386 When using project files, if some errors or warnings are detected during
387 parsing and verbose mode is not in effect (no use of switch
388 -v), then error lines start with the full path name of the project
389 file, rather than its simple file name.
392 .. index:: -g (gnatmake)
395 Enable debugging. This switch is simply passed to the compiler and to the
399 .. index:: -i (gnatmake)
402 In normal mode, ``gnatmake`` compiles all object files and ALI files
403 into the current directory. If the :switch:`-i` switch is used,
404 then instead object files and ALI files that already exist are overwritten
405 in place. This means that once a large project is organized into separate
406 directories in the desired manner, then ``gnatmake`` will automatically
407 maintain and update this organization. If no ALI files are found on the
408 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
409 the new object and ALI files are created in the
410 directory containing the source being compiled. If another organization
411 is desired, where objects and sources are kept in different directories,
412 a useful technique is to create dummy ALI files in the desired directories.
413 When detecting such a dummy file, ``gnatmake`` will be forced to
414 recompile the corresponding source file, and it will be put the resulting
415 object and ALI files in the directory where it found the dummy file.
418 .. index:: -j (gnatmake)
419 .. index:: Parallel make
422 Use ``n`` processes to carry out the (re)compilations. On a multiprocessor
423 machine compilations will occur in parallel. If ``n`` is 0, then the
424 maximum number of parallel compilations is the number of core processors
425 on the platform. In the event of compilation errors, messages from various
426 compilations might get interspersed (but ``gnatmake`` will give you the
427 full ordered list of failing compiles at the end). If this is problematic,
428 rerun the make process with n set to 1 to get a clean list of messages.
431 .. index:: -k (gnatmake)
434 Keep going. Continue as much as possible after a compilation error. To
435 ease the programmer's task in case of compilation errors, the list of
436 sources for which the compile fails is given when ``gnatmake``
439 If ``gnatmake`` is invoked with several :file:`file_names` and with this
440 switch, if there are compilation errors when building an executable,
441 ``gnatmake`` will not attempt to build the following executables.
444 .. index:: -l (gnatmake)
447 Link only. Can be combined with :switch:`-b` to binding
448 and linking. Linking will not be performed if combined with
450 but not with :switch:`-b`.
451 When not combined with :switch:`-b`
452 all the units in the closure of the main program must have been previously
453 compiled and must be up to date, and the main program needs to have been bound.
454 The root unit specified by ``file_name``
455 may be given without extension, with the source extension or, if no GNAT
456 Project File is specified, with the ALI file extension.
459 .. index:: -m (gnatmake)
462 Specify that the minimum necessary amount of recompilations
463 be performed. In this mode ``gnatmake`` ignores time
464 stamp differences when the only
465 modifications to a source file consist in adding/removing comments,
466 empty lines, spaces or tabs. This means that if you have changed the
467 comments in a source file or have simply reformatted it, using this
468 switch will tell ``gnatmake`` not to recompile files that depend on it
469 (provided other sources on which these files depend have undergone no
470 semantic modifications). Note that the debugging information may be
471 out of date with respect to the sources if the :switch:`-m` switch causes
472 a compilation to be switched, so the use of this switch represents a
473 trade-off between compilation time and accurate debugging information.
476 .. index:: Dependencies, producing list
477 .. index:: -M (gnatmake)
480 Check if all objects are up to date. If they are, output the object
481 dependences to :file:`stdout` in a form that can be directly exploited in
482 a :file:`Makefile`. By default, each source file is prefixed with its
483 (relative or absolute) directory name. This name is whatever you
484 specified in the various :switch:`-aI`
485 and :switch:`-I` switches. If you use
486 ``gnatmake -M`` :switch:`-q`
487 (see below), only the source file names,
488 without relative paths, are output. If you just specify the :switch:`-M`
489 switch, dependencies of the GNAT internal system files are omitted. This
490 is typically what you want. If you also specify
491 the :switch:`-a` switch,
492 dependencies of the GNAT internal files are also listed. Note that
493 dependencies of the objects in external Ada libraries (see
494 switch :switch:`-aL{dir}` in the following list)
498 .. index:: -n (gnatmake)
501 Don't compile, bind, or link. Checks if all objects are up to date.
502 If they are not, the full name of the first file that needs to be
503 recompiled is printed.
504 Repeated use of this option, followed by compiling the indicated source
505 file, will eventually result in recompiling all required units.
508 .. index:: -o (gnatmake)
510 :switch:`-o {exec_name}`
511 Output executable name. The name of the final executable program will be
512 ``exec_name``. If the :switch:`-o` switch is omitted the default
513 name for the executable will be the name of the input file in appropriate form
514 for an executable file on the host system.
516 This switch cannot be used when invoking ``gnatmake`` with several
520 .. index:: -p (gnatmake)
523 Same as :switch:`--create-missing-dirs`
525 .. index:: -P (gnatmake)
527 :switch:`-P{project}`
528 Use project file ``project``. Only one such switch can be used.
531 :ref:`gnatmake_and_Project_Files`.
534 .. index:: -q (gnatmake)
537 Quiet. When this flag is not set, the commands carried out by
538 ``gnatmake`` are displayed.
541 .. index:: -s (gnatmake)
544 Recompile if compiler switches have changed since last compilation.
545 All compiler switches but -I and -o are taken into account in the
547 orders between different 'first letter' switches are ignored, but
548 orders between same switches are taken into account. For example,
549 :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O`
550 is equivalent to :switch:`-O -g`.
552 This switch is recommended when Integrated Preprocessing is used.
555 .. index:: -u (gnatmake)
558 Unique. Recompile at most the main files. It implies -c. Combined with
559 -f, it is equivalent to calling the compiler directly. Note that using
560 -u with a project file and no main has a special meaning.
563 (See :ref:`Project_Files_and_Main_Subprograms`.)
566 .. index:: -U (gnatmake)
569 When used without a project file or with one or several mains on the command
570 line, is equivalent to -u. When used with a project file and no main
571 on the command line, all sources of all project files are checked and compiled
572 if not up to date, and libraries are rebuilt, if necessary.
575 .. index:: -v (gnatmake)
578 Verbose. Display the reason for all recompilations ``gnatmake``
579 decides are necessary, with the highest verbosity level.
582 .. index:: -vl (gnatmake)
585 Verbosity level Low. Display fewer lines than in verbosity Medium.
588 .. index:: -vm (gnatmake)
591 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
594 .. index:: -vm (gnatmake)
597 Verbosity level High. Equivalent to -v.
601 Indicate the verbosity of the parsing of GNAT project files.
602 See :ref:`Switches_Related_to_Project_Files`.
605 .. index:: -x (gnatmake)
608 Indicate that sources that are not part of any Project File may be compiled.
609 Normally, when using Project Files, only sources that are part of a Project
610 File may be compile. When this switch is used, a source outside of all Project
611 Files may be compiled. The ALI file and the object file will be put in the
612 object directory of the main Project. The compilation switches used will only
613 be those specified on the command line. Even when
614 :switch:`-x` is used, mains specified on the
615 command line need to be sources of a project file.
618 :switch:`-X{name}={value}`
619 Indicate that external variable ``name`` has the value ``value``.
620 The Project Manager will use this value for occurrences of
621 ``external(name)`` when parsing the project file.
622 :ref:`Switches_Related_to_Project_Files`.
625 .. index:: -z (gnatmake)
628 No main subprogram. Bind and link the program even if the unit name
629 given on the command line is a package name. The resulting executable
630 will execute the elaboration routines of the package and its closure,
631 then the finalization routines.
634 .. rubric:: GCC switches
636 Any uppercase or multi-character switch that is not a ``gnatmake`` switch
637 is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
640 .. rubric:: Source and library search path switches
642 .. index:: -aI (gnatmake)
645 When looking for source files also look in directory ``dir``.
646 The order in which source files search is undertaken is
647 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
650 .. index:: -aL (gnatmake)
653 Consider ``dir`` as being an externally provided Ada library.
654 Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI`
655 files have been located in directory ``dir``. This allows you to have
656 missing bodies for the units in ``dir`` and to ignore out of date bodies
657 for the same units. You still need to specify
658 the location of the specs for these units by using the switches
659 :switch:`-aI{dir}` or :switch:`-I{dir}`.
660 Note: this switch is provided for compatibility with previous versions
661 of ``gnatmake``. The easier method of causing standard libraries
662 to be excluded from consideration is to write-protect the corresponding
666 .. index:: -aO (gnatmake)
669 When searching for library and object files, look in directory
670 ``dir``. The order in which library files are searched is described in
671 :ref:`Search_Paths_for_gnatbind`.
674 .. index:: Search paths, for gnatmake
675 .. index:: -A (gnatmake)
678 Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`.
681 .. index:: -I (gnatmake)
684 Equivalent to :switch:`-aO{dir} -aI{dir}`.
687 .. index:: -I- (gnatmake)
688 .. index:: Source files, suppressing search
691 Do not look for source files in the directory containing the source
692 file named in the command line.
693 Do not look for ALI or object files in the directory
694 where ``gnatmake`` was invoked.
697 .. index:: -L (gnatmake)
698 .. index:: Linker libraries
701 Add directory ``dir`` to the list of directories in which the linker
702 will search for libraries. This is equivalent to
703 :switch:`-largs` :switch:`-L{dir}`.
704 Furthermore, under Windows, the sources pointed to by the libraries path
705 set in the registry are not searched for.
708 .. index:: -nostdinc (gnatmake)
711 Do not look for source files in the system default directory.
714 .. index:: -nostdlib (gnatmake)
717 Do not look for library files in the system default directory.
720 .. index:: --RTS (gnatmake)
722 :switch:`--RTS={rts-path}`
723 Specifies the default location of the run-time library. GNAT looks for the
725 in the following directories, and stops as soon as a valid run-time is found
726 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
727 :file:`ada_object_path` present):
729 * *<current directory>/$rts_path*
731 * *<default-search-dir>/$rts_path*
733 * *<default-search-dir>/rts-$rts_path*
735 * The selected path is handled like a normal RTS path.
738 .. _Mode_Switches_for_gnatmake:
740 Mode Switches for ``gnatmake``
741 ------------------------------
743 The mode switches (referred to as ``mode_switches``) allow the
744 inclusion of switches that are to be passed to the compiler itself, the
745 binder or the linker. The effect of a mode switch is to cause all
746 subsequent switches up to the end of the switch list, or up to the next
747 mode switch, to be interpreted as switches to be passed on to the
748 designated component of GNAT.
750 .. index:: -cargs (gnatmake)
752 :switch:`-cargs {switches}`
753 Compiler switches. Here ``switches`` is a list of switches
754 that are valid switches for ``gcc``. They will be passed on to
755 all compile steps performed by ``gnatmake``.
758 .. index:: -bargs (gnatmake)
760 :switch:`-bargs {switches}`
761 Binder switches. Here ``switches`` is a list of switches
762 that are valid switches for ``gnatbind``. They will be passed on to
763 all bind steps performed by ``gnatmake``.
766 .. index:: -largs (gnatmake)
768 :switch:`-largs {switches}`
769 Linker switches. Here ``switches`` is a list of switches
770 that are valid switches for ``gnatlink``. They will be passed on to
771 all link steps performed by ``gnatmake``.
774 .. index:: -margs (gnatmake)
776 :switch:`-margs {switches}`
777 Make switches. The switches are directly interpreted by ``gnatmake``,
778 regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs`
782 .. _Notes_on_the_Command_Line:
784 Notes on the Command Line
785 -------------------------
787 This section contains some additional useful notes on the operation
788 of the ``gnatmake`` command.
790 .. index:: Recompilation (by gnatmake)
792 * If ``gnatmake`` finds no ALI files, it recompiles the main program
793 and all other units required by the main program.
794 This means that ``gnatmake``
795 can be used for the initial compile, as well as during subsequent steps of
796 the development cycle.
798 * If you enter ``gnatmake foo.adb``, where ``foo``
799 is a subunit or body of a generic unit, ``gnatmake`` recompiles
800 :file:`foo.adb` (because it finds no ALI) and stops, issuing a
803 * In ``gnatmake`` the switch :switch:`-I`
804 is used to specify both source and
805 library file paths. Use :switch:`-aI`
806 instead if you just want to specify
807 source paths only and :switch:`-aO`
808 if you want to specify library paths
811 * ``gnatmake`` will ignore any files whose ALI file is write-protected.
812 This may conveniently be used to exclude standard libraries from
813 consideration and in particular it means that the use of the
814 :switch:`-f` switch will not recompile these files
815 unless :switch:`-a` is also specified.
817 * ``gnatmake`` has been designed to make the use of Ada libraries
818 particularly convenient. Assume you have an Ada library organized
819 as follows: *obj-dir* contains the objects and ALI files for
820 of your Ada compilation units,
821 whereas *include-dir* contains the
822 specs of these units, but no bodies. Then to compile a unit
823 stored in ``main.adb``, which uses this Ada library you would just type:
827 $ gnatmake -aI`include-dir` -aL`obj-dir` main
829 * Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)`
830 switch provides a mechanism for avoiding unnecessary recompilations. Using
832 you can update the comments/format of your
833 source files without having to recompile everything. Note, however, that
834 adding or deleting lines in a source files may render its debugging
835 info obsolete. If the file in question is a spec, the impact is rather
836 limited, as that debugging info will only be useful during the
837 elaboration phase of your program. For bodies the impact can be more
838 significant. In all events, your debugger will warn you if a source file
839 is more recent than the corresponding object, and alert you to the fact
840 that the debugging information may be out of date.
843 .. _How_gnatmake_Works:
845 How ``gnatmake`` Works
846 ----------------------
848 Generally ``gnatmake`` automatically performs all necessary
849 recompilations and you don't need to worry about how it works. However,
850 it may be useful to have some basic understanding of the ``gnatmake``
851 approach and in particular to understand how it uses the results of
852 previous compilations without incorrectly depending on them.
854 First a definition: an object file is considered *up to date* if the
855 corresponding ALI file exists and if all the source files listed in the
856 dependency section of this ALI file have time stamps matching those in
857 the ALI file. This means that neither the source file itself nor any
858 files that it depends on have been modified, and hence there is no need
859 to recompile this file.
861 ``gnatmake`` works by first checking if the specified main unit is up
862 to date. If so, no compilations are required for the main unit. If not,
863 ``gnatmake`` compiles the main program to build a new ALI file that
864 reflects the latest sources. Then the ALI file of the main unit is
865 examined to find all the source files on which the main program depends,
866 and ``gnatmake`` recursively applies the above procedure on all these
869 This process ensures that ``gnatmake`` only trusts the dependencies
870 in an existing ALI file if they are known to be correct. Otherwise it
871 always recompiles to determine a new, guaranteed accurate set of
872 dependencies. As a result the program is compiled 'upside down' from what may
873 be more familiar as the required order of compilation in some other Ada
874 systems. In particular, clients are compiled before the units on which
875 they depend. The ability of GNAT to compile in any order is critical in
876 allowing an order of compilation to be chosen that guarantees that
877 ``gnatmake`` will recompute a correct set of new dependencies if
880 When invoking ``gnatmake`` with several ``file_names``, if a unit is
881 imported by several of the executables, it will be recompiled at most once.
883 Note: when using non-standard naming conventions
884 (:ref:`Using_Other_File_Names`), changing through a configuration pragmas
885 file the version of a source and invoking ``gnatmake`` to recompile may
886 have no effect, if the previous version of the source is still accessible
887 by ``gnatmake``. It may be necessary to use the switch
891 .. _Examples_of_gnatmake_Usage:
893 Examples of ``gnatmake`` Usage
894 ------------------------------
897 Compile all files necessary to bind and link the main program
898 :file:`hello.adb` (containing unit ``Hello``) and bind and link the
899 resulting object files to generate an executable file :file:`hello`.
901 *gnatmake main1 main2 main3*
902 Compile all files necessary to bind and link the main programs
903 :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb`
904 (containing unit ``Main2``) and :file:`main3.adb`
905 (containing unit ``Main3``) and bind and link the resulting object files
906 to generate three executable files :file:`main1`,
907 :file:`main2` and :file:`main3`.
909 *gnatmake -q Main_Unit -cargs -O2 -bargs -l*
910 Compile all files necessary to bind and link the main program unit
911 ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will
912 be done with optimization level 2 and the order of elaboration will be
913 listed by the binder. ``gnatmake`` will operate in quiet mode, not
914 displaying commands it is executing.
917 .. _Compiling_with_gcc:
919 Compiling with ``gcc``
920 ======================
922 This section discusses how to compile Ada programs using the ``gcc``
923 command. It also describes the set of switches
924 that can be used to control the behavior of the compiler.
926 .. _Compiling_Programs:
931 The first step in creating an executable program is to compile the units
932 of the program using the ``gcc`` command. You must compile the
935 * the body file (:file:`.adb`) for a library level subprogram or generic
938 * the spec file (:file:`.ads`) for a library level package or generic
939 package that has no body
941 * the body file (:file:`.adb`) for a library level package
942 or generic package that has a body
944 You need *not* compile the following files
946 * the spec of a library unit which has a body
950 because they are compiled as part of compiling related units. GNAT
952 when the corresponding body is compiled, and subunits when the parent is
955 .. index:: cannot generate code
957 If you attempt to compile any of these files, you will get one of the
958 following error messages (where ``fff`` is the name of the file you
963 cannot generate code for file ``fff`` (package spec)
964 to check package spec, use -gnatc
966 cannot generate code for file ``fff`` (missing subunits)
967 to check parent unit, use -gnatc
969 cannot generate code for file ``fff`` (subprogram spec)
970 to check subprogram spec, use -gnatc
972 cannot generate code for file ``fff`` (subunit)
973 to check subunit, use -gnatc
976 As indicated by the above error messages, if you want to submit
977 one of these files to the compiler to check for correct semantics
978 without generating code, then use the :switch:`-gnatc` switch.
980 The basic command for compiling a file containing an Ada unit is:
984 $ gcc -c [switches] <file name>
986 where ``file name`` is the name of the Ada file (usually
987 having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
989 :switch:`-c` switch to tell ``gcc`` to compile, but not link, the file.
990 The result of a successful compilation is an object file, which has the
991 same name as the source file but an extension of :file:`.o` and an Ada
992 Library Information (ALI) file, which also has the same name as the
993 source file, but with :file:`.ali` as the extension. GNAT creates these
994 two output files in the current directory, but you may specify a source
995 file in any directory using an absolute or relative path specification
996 containing the directory information.
998 TESTING: the :switch:`--foobar{NN}` switch
1002 ``gcc`` is actually a driver program that looks at the extensions of
1003 the file arguments and loads the appropriate compiler. For example, the
1004 GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`.
1005 These programs are in directories known to the driver program (in some
1006 configurations via environment variables you set), but need not be in
1007 your path. The ``gcc`` driver also calls the assembler and any other
1008 utilities needed to complete the generation of the required object
1011 It is possible to supply several file names on the same ``gcc``
1012 command. This causes ``gcc`` to call the appropriate compiler for
1013 each file. For example, the following command lists two separate
1014 files to be compiled:
1018 $ gcc -c x.adb y.adb
1021 calls ``gnat1`` (the Ada compiler) twice to compile :file:`x.adb` and
1023 The compiler generates two object files :file:`x.o` and :file:`y.o`
1024 and the two ALI files :file:`x.ali` and :file:`y.ali`.
1026 Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a
1027 list of available ``gcc`` switches.
1029 .. _Search_Paths_and_the_Run-Time_Library_RTL:
1031 Search Paths and the Run-Time Library (RTL)
1032 -------------------------------------------
1034 With the GNAT source-based library system, the compiler must be able to
1035 find source files for units that are needed by the unit being compiled.
1036 Search paths are used to guide this process.
1038 The compiler compiles one source file whose name must be given
1039 explicitly on the command line. In other words, no searching is done
1040 for this file. To find all other source files that are needed (the most
1041 common being the specs of units), the compiler examines the following
1042 directories, in the following order:
1044 * The directory containing the source file of the main unit being compiled
1045 (the file name on the command line).
1047 * Each directory named by an :switch:`-I` switch given on the ``gcc``
1048 command line, in the order given.
1050 .. index:: ADA_PRJ_INCLUDE_FILE
1052 * Each of the directories listed in the text file whose name is given
1053 by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable.
1054 :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat
1055 driver when project files are used. It should not normally be set
1058 .. index:: ADA_INCLUDE_PATH
1060 * Each of the directories listed in the value of the
1061 :envvar:`ADA_INCLUDE_PATH` environment variable.
1062 Construct this value
1063 exactly as the :envvar:`PATH` environment variable: a list of directory
1064 names separated by colons (semicolons when working with the NT version).
1066 * The content of the :file:`ada_source_path` file which is part of the GNAT
1067 installation tree and is used to store standard libraries such as the
1068 GNAT Run Time Library (RTL) source files.
1069 :ref:`Installing_a_library`
1071 Specifying the switch :switch:`-I-`
1072 inhibits the use of the directory
1073 containing the source file named in the command line. You can still
1074 have this directory on your search path, but in this case it must be
1075 explicitly requested with a :switch:`-I` switch.
1077 Specifying the switch :switch:`-nostdinc`
1078 inhibits the search of the default location for the GNAT Run Time
1079 Library (RTL) source files.
1081 The compiler outputs its object files and ALI files in the current
1083 Caution: The object file can be redirected with the :switch:`-o` switch;
1084 however, ``gcc`` and ``gnat1`` have not been coordinated on this
1085 so the :file:`ALI` file will not go to the right place. Therefore, you should
1086 avoid using the :switch:`-o` switch.
1088 .. index:: System.IO
1090 The packages ``Ada``, ``System``, and ``Interfaces`` and their
1091 children make up the GNAT RTL, together with the simple ``System.IO``
1092 package used in the ``"Hello World"`` example. The sources for these units
1093 are needed by the compiler and are kept together in one directory. Not
1094 all of the bodies are needed, but all of the sources are kept together
1095 anyway. In a normal installation, you need not specify these directory
1096 names when compiling or binding. Either the environment variables or
1097 the built-in defaults cause these files to be found.
1099 In addition to the language-defined hierarchies (``System``, ``Ada`` and
1100 ``Interfaces``), the GNAT distribution provides a fourth hierarchy,
1101 consisting of child units of ``GNAT``. This is a collection of generally
1102 useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual`
1103 for further details.
1105 Besides simplifying access to the RTL, a major use of search paths is
1106 in compiling sources from multiple directories. This can make
1107 development environments much more flexible.
1109 .. _Order_of_Compilation_Issues:
1111 Order of Compilation Issues
1112 ---------------------------
1114 If, in our earlier example, there was a spec for the ``hello``
1115 procedure, it would be contained in the file :file:`hello.ads`; yet this
1116 file would not have to be explicitly compiled. This is the result of the
1117 model we chose to implement library management. Some of the consequences
1118 of this model are as follows:
1120 * There is no point in compiling specs (except for package
1121 specs with no bodies) because these are compiled as needed by clients. If
1122 you attempt a useless compilation, you will receive an error message.
1123 It is also useless to compile subunits because they are compiled as needed
1126 * There are no order of compilation requirements: performing a
1127 compilation never obsoletes anything. The only way you can obsolete
1128 something and require recompilations is to modify one of the
1129 source files on which it depends.
1131 * There is no library as such, apart from the ALI files
1132 (:ref:`The_Ada_Library_Information_Files`, for information on the format
1133 of these files). For now we find it convenient to create separate ALI files,
1134 but eventually the information therein may be incorporated into the object
1137 * When you compile a unit, the source files for the specs of all units
1138 that it |withs|, all its subunits, and the bodies of any generics it
1139 instantiates must be available (reachable by the search-paths mechanism
1140 described above), or you will receive a fatal error message.
1147 The following are some typical Ada compilation command line examples:
1153 Compile body in file :file:`xyz.adb` with all default options.
1157 $ gcc -c -O2 -gnata xyz-def.adb
1159 Compile the child unit package in file :file:`xyz-def.adb` with extensive
1160 optimizations, and pragma ``Assert``/`Debug` statements
1165 $ gcc -c -gnatc abc-def.adb
1167 Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only
1171 .. _Switches_for_gcc:
1176 The ``gcc`` command accepts switches that control the
1177 compilation process. These switches are fully described in this section:
1178 first an alphabetical listing of all switches with a brief description,
1179 and then functionally grouped sets of switches with more detailed
1182 More switches exist for GCC than those documented here, especially
1183 for specific targets. However, their use is not recommended as
1184 they may change code generation in ways that are incompatible with
1185 the Ada run-time library, or can cause inconsistencies between
1188 .. _Alphabetical_List_of_All_Switches:
1190 Alphabetical List of All Switches
1191 ---------------------------------
1195 :switch:`-b {target}`
1196 Compile your program to run on ``target``, which is the name of a
1197 system configuration. You must have a GNAT cross-compiler built if
1198 ``target`` is not the same as your host system.
1204 Load compiler executables (for example, ``gnat1``, the Ada compiler)
1205 from ``dir`` instead of the default location. Only use this switch
1206 when multiple versions of the GNAT compiler are available.
1207 See the "Options for Directory Search" section in the
1208 :title:`Using the GNU Compiler Collection (GCC)` manual for further details.
1209 You would normally use the :switch:`-b` or :switch:`-V` switch instead.
1214 Compile. Always use this switch when compiling Ada programs.
1216 Note: for some other languages when using ``gcc``, notably in
1217 the case of C and C++, it is possible to use
1218 use ``gcc`` without a :switch:`-c` switch to
1219 compile and link in one step. In the case of GNAT, you
1220 cannot use this approach, because the binder must be run
1221 and ``gcc`` cannot be used to run the GNAT binder.
1224 .. index:: -fcallgraph-info (gcc)
1226 :switch:`-fcallgraph-info[=su,da]`
1227 Makes the compiler output callgraph information for the program, on a
1228 per-file basis. The information is generated in the VCG format. It can
1229 be decorated with additional, per-node and/or per-edge information, if a
1230 list of comma-separated markers is additionally specified. When the
1231 ``su`` marker is specified, the callgraph is decorated with stack usage
1232 information; it is equivalent to :switch:`-fstack-usage`. When the ``da``
1233 marker is specified, the callgraph is decorated with information about
1234 dynamically allocated objects.
1237 .. index:: -fdump-scos (gcc)
1239 :switch:`-fdump-scos`
1240 Generates SCO (Source Coverage Obligation) information in the ALI file.
1241 This information is used by advanced coverage tools. See unit :file:`SCOs`
1242 in the compiler sources for details in files :file:`scos.ads` and
1246 .. index:: -fgnat-encodings (gcc)
1248 :switch:`-fgnat-encodings=[all|gdb|minimal]`
1249 This switch controls the balance between GNAT encodings and standard DWARF
1250 emitted in the debug information.
1253 .. index:: -flto (gcc)
1255 :switch:`-flto[={n}]`
1256 Enables Link Time Optimization. This switch must be used in conjunction
1257 with the :switch:`-Ox` switches (but not with the :switch:`-gnatn` switch
1258 since it is a full replacement for the latter) and instructs the compiler
1259 to defer most optimizations until the link stage. The advantage of this
1260 approach is that the compiler can do a whole-program analysis and choose
1261 the best interprocedural optimization strategy based on a complete view
1262 of the program, instead of a fragmentary view with the usual approach.
1263 This can also speed up the compilation of big programs and reduce the
1264 size of the executable, compared with a traditional per-unit compilation
1265 with inlining across units enabled by the :switch:`-gnatn` switch.
1266 The drawback of this approach is that it may require more memory and that
1267 the debugging information generated by -g with it might be hardly usable.
1268 The switch, as well as the accompanying :switch:`-Ox` switches, must be
1269 specified both for the compilation and the link phases.
1270 If the ``n`` parameter is specified, the optimization and final code
1271 generation at link time are executed using ``n`` parallel jobs by
1272 means of an installed ``make`` program.
1275 .. index:: -fno-inline (gcc)
1277 :switch:`-fno-inline`
1278 Suppresses all inlining, unless requested with pragma ``Inline_Always``. The
1279 effect is enforced regardless of other optimization or inlining switches.
1280 Note that inlining can also be suppressed on a finer-grained basis with
1281 pragma ``No_Inline``.
1284 .. index:: -fno-inline-functions (gcc)
1286 :switch:`-fno-inline-functions`
1287 Suppresses automatic inlining of subprograms, which is enabled
1288 if :switch:`-O3` is used.
1291 .. index:: -fno-inline-small-functions (gcc)
1293 :switch:`-fno-inline-small-functions`
1294 Suppresses automatic inlining of small subprograms, which is enabled
1295 if :switch:`-O2` is used.
1298 .. index:: -fno-inline-functions-called-once (gcc)
1300 :switch:`-fno-inline-functions-called-once`
1301 Suppresses inlining of subprograms local to the unit and called once
1302 from within it, which is enabled if :switch:`-O1` is used.
1305 .. index:: -fno-ivopts (gcc)
1307 :switch:`-fno-ivopts`
1308 Suppresses high-level loop induction variable optimizations, which are
1309 enabled if :switch:`-O1` is used. These optimizations are generally
1310 profitable but, for some specific cases of loops with numerous uses
1311 of the iteration variable that follow a common pattern, they may end
1312 up destroying the regularity that could be exploited at a lower level
1313 and thus producing inferior code.
1316 .. index:: -fno-strict-aliasing (gcc)
1318 :switch:`-fno-strict-aliasing`
1319 Causes the compiler to avoid assumptions regarding non-aliasing
1320 of objects of different types. See
1321 :ref:`Optimization_and_Strict_Aliasing` for details.
1324 .. index:: -fno-strict-overflow (gcc)
1326 :switch:`-fno-strict-overflow`
1327 Causes the compiler to avoid assumptions regarding the rules of signed
1328 integer overflow. These rules specify that signed integer overflow will
1329 result in a Constraint_Error exception at run time and are enforced in
1330 default mode by the compiler, so this switch should not be necessary in
1331 normal operating mode. It might be useful in conjunction with :switch:`-gnato0`
1332 for very peculiar cases of low-level programming.
1335 .. index:: -fstack-check (gcc)
1337 :switch:`-fstack-check`
1338 Activates stack checking.
1339 See :ref:`Stack_Overflow_Checking` for details.
1342 .. index:: -fstack-usage (gcc)
1344 :switch:`-fstack-usage`
1345 Makes the compiler output stack usage information for the program, on a
1346 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
1352 Generate debugging information. This information is stored in the object
1353 file and copied from there to the final executable file by the linker,
1354 where it can be read by the debugger. You must use the
1355 :switch:`-g` switch if you plan on using the debugger.
1358 .. index:: -gnat05 (gcc)
1361 Allow full Ada 2005 features.
1364 .. index:: -gnat12 (gcc)
1367 Allow full Ada 2012 features.
1369 .. index:: -gnat83 (gcc)
1371 .. index:: -gnat2005 (gcc)
1374 Allow full Ada 2005 features (same as :switch:`-gnat05`)
1377 .. index:: -gnat2012 (gcc)
1380 Allow full Ada 2012 features (same as :switch:`-gnat12`)
1384 Enforce Ada 83 restrictions.
1387 .. index:: -gnat95 (gcc)
1390 Enforce Ada 95 restrictions.
1392 Note: for compatibility with some Ada 95 compilers which support only
1393 the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can
1394 be used along with :switch:`-gnat95` to achieve a similar effect with GNAT.
1396 :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword
1397 and handle its associated semantic checks, even in Ada 95 mode.
1400 .. index:: -gnata (gcc)
1403 Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be
1404 activated. Note that these pragmas can also be controlled using the
1405 configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``.
1406 It also activates pragmas ``Check``, ``Precondition``, and
1407 ``Postcondition``. Note that these pragmas can also be controlled
1408 using the configuration pragma ``Check_Policy``. In Ada 2012, it
1409 also activates all assertions defined in the RM as aspects: preconditions,
1410 postconditions, type invariants and (sub)type predicates. In all Ada modes,
1411 corresponding pragmas for type invariants and (sub)type predicates are
1412 also activated. The default is that all these assertions are disabled,
1413 and have no effect, other than being checked for syntactic validity, and
1414 in the case of subtype predicates, constructions such as membership tests
1415 still test predicates even if assertions are turned off.
1418 .. index:: -gnatA (gcc)
1421 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
1425 .. index:: -gnatb (gcc)
1428 Generate brief messages to :file:`stderr` even if verbose mode set.
1431 .. index:: -gnatB (gcc)
1434 Assume no invalid (bad) values except for 'Valid attribute use
1435 (:ref:`Validity_Checking`).
1438 .. index:: -gnatc (gcc)
1441 Check syntax and semantics only (no code generation attempted). When the
1442 compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is
1443 only given to the compiler (after :switch:`-cargs` or in package Compiler of
1444 the project file, ``gnatmake`` will fail because it will not find the
1445 object file after compilation. If ``gnatmake`` is called with
1446 :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package
1447 Builder of the project file) then ``gnatmake`` will not fail because
1448 it will not look for the object files after compilation, and it will not try
1452 .. index:: -gnatC (gcc)
1455 Generate CodePeer intermediate format (no code generation attempted).
1456 This switch will generate an intermediate representation suitable for
1457 use by CodePeer (:file:`.scil` files). This switch is not compatible with
1458 code generation (it will, among other things, disable some switches such
1459 as -gnatn, and enable others such as -gnata).
1462 .. index:: -gnatd (gcc)
1465 Specify debug options for the compiler. The string of characters after
1466 the :switch:`-gnatd` specify the specific debug options. The possible
1467 characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
1468 compiler source file :file:`debug.adb` for details of the implemented
1469 debug options. Certain debug options are relevant to applications
1470 programmers, and these are documented at appropriate points in this
1474 .. index:: -gnatD[nn] (gcc)
1477 Create expanded source files for source level debugging. This switch
1478 also suppresses generation of cross-reference information
1479 (see :switch:`-gnatx`). Note that this switch is not allowed if a previous
1480 -gnatR switch has been given, since these two switches are not compatible.
1483 .. index:: -gnateA (gcc)
1486 Check that the actual parameters of a subprogram call are not aliases of one
1487 another. To qualify as aliasing, the actuals must denote objects of a composite
1488 type, their memory locations must be identical or overlapping, and at least one
1489 of the corresponding formal parameters must be of mode OUT or IN OUT.
1494 type Rec_Typ is record
1495 Data : Integer := 0;
1498 function Self (Val : Rec_Typ) return Rec_Typ is
1503 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
1506 end Detect_Aliasing;
1510 Detect_Aliasing (Obj, Obj);
1511 Detect_Aliasing (Obj, Self (Obj));
1514 In the example above, the first call to ``Detect_Aliasing`` fails with a
1515 ``Program_Error`` at run time because the actuals for ``Val_1`` and
1516 ``Val_2`` denote the same object. The second call executes without raising
1517 an exception because ``Self(Obj)`` produces an anonymous object which does
1518 not share the memory location of ``Obj``.
1521 .. index:: -gnatec (gcc)
1523 :switch:`-gnatec={path}`
1524 Specify a configuration pragma file
1525 (the equal sign is optional)
1526 (:ref:`The_Configuration_Pragmas_Files`).
1529 .. index:: -gnateC (gcc)
1532 Generate CodePeer messages in a compiler-like format. This switch is only
1533 effective if :switch:`-gnatcC` is also specified and requires an installation
1537 .. index:: -gnated (gcc)
1540 Disable atomic synchronization
1543 .. index:: -gnateD (gcc)
1545 :switch:`-gnateDsymbol[={value}]`
1546 Defines a symbol, associated with ``value``, for preprocessing.
1547 (:ref:`Integrated_Preprocessing`).
1550 .. index:: -gnateE (gcc)
1553 Generate extra information in exception messages. In particular, display
1554 extra column information and the value and range associated with index and
1555 range check failures, and extra column information for access checks.
1556 In cases where the compiler is able to determine at compile time that
1557 a check will fail, it gives a warning, and the extra information is not
1558 produced at run time.
1561 .. index:: -gnatef (gcc)
1564 Display full source path name in brief error messages.
1567 .. index:: -gnateF (gcc)
1570 Check for overflow on all floating-point operations, including those
1571 for unconstrained predefined types. See description of pragma
1572 ``Check_Float_Overflow`` in GNAT RM.
1575 .. index:: -gnateg (gcc)
1580 The :switch:`-gnatc` switch must always be specified before this switch, e.g.
1581 :switch:`-gnatceg`. Generate a C header from the Ada input file. See
1582 :ref:`Generating_C_Headers_for_Ada_Specifications` for more
1586 .. index:: -gnateG (gcc)
1589 Save result of preprocessing in a text file.
1592 .. index:: -gnatei (gcc)
1594 :switch:`-gnatei{nnn}`
1595 Set maximum number of instantiations during compilation of a single unit to
1596 ``nnn``. This may be useful in increasing the default maximum of 8000 for
1597 the rare case when a single unit legitimately exceeds this limit.
1600 .. index:: -gnateI (gcc)
1602 :switch:`-gnateI{nnn}`
1603 Indicates that the source is a multi-unit source and that the index of the
1604 unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need
1605 to be a valid index in the multi-unit source.
1608 .. index:: -gnatel (gcc)
1611 This switch can be used with the static elaboration model to issue info
1613 where implicit ``pragma Elaborate`` and ``pragma Elaborate_All``
1614 are generated. This is useful in diagnosing elaboration circularities
1615 caused by these implicit pragmas when using the static elaboration
1616 model. See See the section in this guide on elaboration checking for
1617 further details. These messages are not generated by default, and are
1618 intended only for temporary use when debugging circularity problems.
1621 .. index:: -gnatel (gcc)
1624 This switch turns off the info messages about implicit elaboration pragmas.
1627 .. index:: -gnatem (gcc)
1629 :switch:`-gnatem={path}`
1630 Specify a mapping file
1631 (the equal sign is optional)
1632 (:ref:`Units_to_Sources_Mapping_Files`).
1635 .. index:: -gnatep (gcc)
1637 :switch:`-gnatep={file}`
1638 Specify a preprocessing data file
1639 (the equal sign is optional)
1640 (:ref:`Integrated_Preprocessing`).
1643 .. index:: -gnateP (gcc)
1646 Turn categorization dependency errors into warnings.
1647 Ada requires that units that WITH one another have compatible categories, for
1648 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
1649 these errors become warnings (which can be ignored, or suppressed in the usual
1650 manner). This can be useful in some specialized circumstances such as the
1651 temporary use of special test software.
1654 .. index:: -gnateS (gcc)
1657 Synonym of :switch:`-fdump-scos`, kept for backwards compatibility.
1660 .. index:: -gnatet=file (gcc)
1662 :switch:`-gnatet={path}`
1663 Generate target dependent information. The format of the output file is
1664 described in the section about switch :switch:`-gnateT`.
1667 .. index:: -gnateT (gcc)
1669 :switch:`-gnateT={path}`
1670 Read target dependent information, such as endianness or sizes and alignments
1671 of base type. If this switch is passed, the default target dependent
1672 information of the compiler is replaced by the one read from the input file.
1673 This is used by tools other than the compiler, e.g. to do
1674 semantic analysis of programs that will run on some other target than
1675 the machine on which the tool is run.
1677 The following target dependent values should be defined,
1678 where ``Nat`` denotes a natural integer value, ``Pos`` denotes a
1679 positive integer value, and fields marked with a question mark are
1680 boolean fields, where a value of 0 is False, and a value of 1 is True:
1685 Bits_BE : Nat; -- Bits stored big-endian?
1686 Bits_Per_Unit : Pos; -- Bits in a storage unit
1687 Bits_Per_Word : Pos; -- Bits in a word
1688 Bytes_BE : Nat; -- Bytes stored big-endian?
1689 Char_Size : Pos; -- Standard.Character'Size
1690 Double_Float_Alignment : Nat; -- Alignment of double float
1691 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
1692 Double_Size : Pos; -- Standard.Long_Float'Size
1693 Float_Size : Pos; -- Standard.Float'Size
1694 Float_Words_BE : Nat; -- Float words stored big-endian?
1695 Int_Size : Pos; -- Standard.Integer'Size
1696 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
1697 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
1698 Long_Size : Pos; -- Standard.Long_Integer'Size
1699 Maximum_Alignment : Pos; -- Maximum permitted alignment
1700 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
1701 Pointer_Size : Pos; -- System.Address'Size
1702 Short_Enums : Nat; -- Foreign enums use short size?
1703 Short_Size : Pos; -- Standard.Short_Integer'Size
1704 Strict_Alignment : Nat; -- Strict alignment?
1705 System_Allocator_Alignment : Nat; -- Alignment for malloc calls
1706 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
1707 Words_BE : Nat; -- Words stored big-endian?
1709 ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of
1710 GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be
1711 the number of bits in an addressable storage unit (byte); normally 8.`
1713 ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of
1714 GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word;
1717 ``Double_Float_Alignment``, if not zero, is the maximum alignment that the
1718 compiler can choose by default for a 64-bit floating-point type or object.
1720 ``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
1721 compiler can choose by default for a 64-bit or larger scalar type or object.
1723 ``Maximum_Alignment`` is the maximum alignment that the compiler can choose
1724 by default for a type or object, which is also the maximum alignment that can
1725 be specified in GNAT. It is computed for GCC backends as ``BIGGEST_ALIGNMENT
1726 / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
1727 follows: `Biggest alignment that any data type can require on this machine,
1730 ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
1731 64 for the majority of GCC targets (but can be different on some targets like
1734 ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
1735 documented as follows: `Define this macro to be the value 1 if instructions
1736 will fail to work if given data not on the nominal alignment. If instructions
1737 will merely go slower in that case, define this macro as 0.`
1739 ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
1740 by calls to ``malloc``.
1743 The format of the input file is as follows. First come the values of
1744 the variables defined above, with one line per value:
1751 where ``name`` is the name of the parameter, spelled out in full,
1752 and cased as in the above list, and ``value`` is an unsigned decimal
1753 integer. Two or more blanks separates the name from the value.
1755 All the variables must be present, in alphabetical order (i.e. the
1756 same order as the list above).
1758 Then there is a blank line to separate the two parts of the file. Then
1759 come the lines showing the floating-point types to be registered, with
1760 one line per registered mode:
1765 name digs float_rep size alignment
1768 where ``name`` is the string name of the type (which can have
1769 single spaces embedded in the name (e.g. long double), ``digs`` is
1770 the number of digits for the floating-point type, ``float_rep`` is
1771 the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
1772 AAMP), ``size`` is the size in bits, ``alignment`` is the
1773 alignment in bits. The name is followed by at least two blanks, fields
1774 are separated by at least one blank, and a LF character immediately
1775 follows the alignment field.
1777 Here is an example of a target parameterization file:
1787 Double_Float_Alignment 0
1788 Double_Scalar_Alignment 0
1793 Long_Double_Size 128
1796 Maximum_Alignment 16
1797 Max_Unaligned_Field 64
1801 System_Allocator_Alignment 16
1807 long double 18 I 80 128
1812 .. index:: -gnateu (gcc)
1815 Ignore unrecognized validity, warning, and style switches that
1816 appear after this switch is given. This may be useful when
1817 compiling sources developed on a later version of the compiler
1818 with an earlier version. Of course the earlier version must
1819 support this switch.
1822 .. index:: -gnateV (gcc)
1825 Check that all actual parameters of a subprogram call are valid according to
1826 the rules of validity checking (:ref:`Validity_Checking`).
1829 .. index:: -gnateY (gcc)
1832 Ignore all STYLE_CHECKS pragmas. Full legality checks
1833 are still carried out, but the pragmas have no effect
1834 on what style checks are active. This allows all style
1835 checking options to be controlled from the command line.
1838 .. index:: -gnatE (gcc)
1841 Dynamic elaboration checking mode enabled. For further details see
1842 :ref:`Elaboration_Order_Handling_in_GNAT`.
1845 .. index:: -gnatf (gcc)
1848 Full errors. Multiple errors per line, all undefined references, do not
1849 attempt to suppress cascaded errors.
1852 .. index:: -gnatF (gcc)
1855 Externals names are folded to all uppercase.
1858 .. index:: -gnatg (gcc)
1861 Internal GNAT implementation mode. This should not be used for applications
1862 programs, it is intended only for use by the compiler and its run-time
1863 library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
1864 implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
1865 warnings and all standard style options are turned on. All warnings and style
1866 messages are treated as errors.
1869 .. index:: -gnatG[nn] (gcc)
1872 List generated expanded code in source form.
1875 .. index:: -gnath (gcc)
1878 Output usage information. The output is written to :file:`stdout`.
1881 .. index:: -gnatH (gcc)
1884 Legacy elaboration-checking mode enabled. When this switch is in effect,
1885 the pre-18.x access-before-elaboration model becomes the de facto model.
1886 For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1889 .. index:: -gnati (gcc)
1892 Identifier character set (``c`` = 1/2/3/4/8/9/p/f/n/w).
1893 For details of the possible selections for ``c``,
1894 see :ref:`Character_Set_Control`.
1897 .. index:: -gnatI (gcc)
1900 Ignore representation clauses. When this switch is used,
1901 representation clauses are treated as comments. This is useful
1902 when initially porting code where you want to ignore rep clause
1903 problems, and also for compiling foreign code (particularly
1904 for use with ASIS). The representation clauses that are ignored
1905 are: enumeration_representation_clause, record_representation_clause,
1906 and attribute_definition_clause for the following attributes:
1907 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1908 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
1909 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
1910 Note that this option should be used only for compiling -- the
1911 code is likely to malfunction at run time.
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. For further
1939 details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1942 .. index:: -gnatk (gcc)
1944 :switch:`-gnatk={n}`
1945 Limit file names to ``n`` (1-999) characters (``k`` = krunch).
1948 .. index:: -gnatl (gcc)
1951 Output full source listing with embedded error messages.
1954 .. index:: -gnatL (gcc)
1957 Used in conjunction with -gnatG or -gnatD to intersperse original
1958 source lines (as comment lines with line numbers) in the expanded
1962 .. index:: -gnatm (gcc)
1964 :switch:`-gnatm={n}`
1965 Limit number of detected error or warning messages to ``n``
1966 where ``n`` is in the range 1..999999. The default setting if
1967 no switch is given is 9999. If the number of warnings reaches this
1968 limit, then a message is output and further warnings are suppressed,
1969 but the compilation is continued. If the number of error messages
1970 reaches this limit, then a message is output and the compilation
1971 is abandoned. The equal sign here is optional. A value of zero
1972 means that no limit applies.
1975 .. index:: -gnatn (gcc)
1977 :switch:`-gnatn[12]`
1978 Activate inlining across units for subprograms for which pragma ``Inline``
1979 is specified. This inlining is performed by the GCC back-end. An optional
1980 digit sets the inlining level: 1 for moderate inlining across units
1981 or 2 for full inlining across units. If no inlining level is specified,
1982 the compiler will pick it based on the optimization level.
1985 .. index:: -gnatN (gcc)
1988 Activate front end inlining for subprograms for which
1989 pragma ``Inline`` is specified. This inlining is performed
1990 by the front end and will be visible in the
1991 :switch:`-gnatG` output.
1993 When using a gcc-based back end (in practice this means using any version
1994 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
1995 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
1996 Historically front end inlining was more extensive than the gcc back end
1997 inlining, but that is no longer the case.
2000 .. index:: -gnato0 (gcc)
2003 Suppresses overflow checking. This causes the behavior of the compiler to
2004 match the default for older versions where overflow checking was suppressed
2005 by default. This is equivalent to having
2006 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
2009 .. index:: -gnato?? (gcc)
2012 Set default mode for handling generation of code to avoid intermediate
2013 arithmetic overflow. Here ``??`` is two digits, a
2014 single digit, or nothing. Each digit is one of the digits ``1``
2017 ===== ===============================================================
2018 Digit Interpretation
2019 ----- ---------------------------------------------------------------
2020 *1* All intermediate overflows checked against base type (``STRICT``)
2021 *2* Minimize intermediate overflows (``MINIMIZED``)
2022 *3* Eliminate intermediate overflows (``ELIMINATED``)
2023 ===== ===============================================================
2025 If only one digit appears, then it applies to all
2026 cases; if two digits are given, then the first applies outside
2027 assertions, pre/postconditions, and type invariants, and the second
2028 applies within assertions, pre/postconditions, and type invariants.
2030 If no digits follow the :switch:`-gnato`, then it is equivalent to
2032 causing all intermediate overflows to be handled in strict
2035 This switch also causes arithmetic overflow checking to be performed
2036 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
2038 The default if no option :switch:`-gnato` is given is that overflow handling
2039 is in ``STRICT`` mode (computations done using the base type), and that
2040 overflow checking is enabled.
2042 Note that division by zero is a separate check that is not
2043 controlled by this switch (divide-by-zero checking is on by default).
2045 See also :ref:`Specifying_the_Desired_Mode`.
2048 .. index:: -gnatp (gcc)
2051 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
2052 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
2055 .. index:: -gnat-p (gcc)
2058 Cancel effect of previous :switch:`-gnatp` switch.
2061 .. index:: -gnatP (gcc)
2064 Enable polling. This is required on some systems (notably Windows NT) to
2065 obtain asynchronous abort and asynchronous transfer of control capability.
2066 See ``Pragma_Polling`` in the :title:`GNAT_Reference_Manual` for full
2070 .. index:: -gnatq (gcc)
2073 Don't quit. Try semantics, even if parse errors.
2076 .. index:: -gnatQ (gcc)
2079 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2080 Note that code generation is still suppressed in the presence of any
2081 errors, so even with :switch:`-gnatQ` no object file is generated.
2084 .. index:: -gnatr (gcc)
2087 Treat pragma Restrictions as Restriction_Warnings.
2090 .. index:: -gnatR (gcc)
2092 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
2093 Output representation information for declared types, objects and
2094 subprograms. Note that this switch is not allowed if a previous
2095 :switch:`-gnatD` switch has been given, since these two switches
2099 .. index:: -gnats (gcc)
2105 .. index:: -gnatS (gcc)
2108 Print package Standard.
2111 .. index:: -gnatT (gcc)
2113 :switch:`-gnatT{nnn}`
2114 All compiler tables start at ``nnn`` times usual starting size.
2117 .. index:: -gnatu (gcc)
2120 List units for this compilation.
2123 .. index:: -gnatU (gcc)
2126 Tag all error messages with the unique string 'error:'
2129 .. index:: -gnatv (gcc)
2132 Verbose mode. Full error output with source lines to :file:`stdout`.
2135 .. index:: -gnatV (gcc)
2138 Control level of validity checking (:ref:`Validity_Checking`).
2141 .. index:: -gnatw (gcc)
2143 :switch:`-gnatw{xxx}`
2145 ``xxx`` is a string of option letters that denotes
2146 the exact warnings that
2147 are enabled or disabled (:ref:`Warning_Message_Control`).
2150 .. index:: -gnatW (gcc)
2153 Wide character encoding method
2154 (``e``\ =n/h/u/s/e/8).
2157 .. index:: -gnatx (gcc)
2160 Suppress generation of cross-reference information.
2163 .. index:: -gnatX (gcc)
2166 Enable GNAT implementation extensions and latest Ada version.
2169 .. index:: -gnaty (gcc)
2172 Enable built-in style checks (:ref:`Style_Checking`).
2175 .. index:: -gnatz (gcc)
2178 Distribution stub generation and compilation
2179 (``m``\ =r/c for receiver/caller stubs).
2187 Direct GNAT to search the ``dir`` directory for source files needed by
2188 the current compilation
2189 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2192 .. index:: -I- (gcc)
2197 Except for the source file named in the command line, do not look for source
2198 files in the directory containing the source file named in the command line
2199 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2205 This switch is used in ``gcc`` to redirect the generated object file
2206 and its associated ALI file. Beware of this switch with GNAT, because it may
2207 cause the object file and ALI file to have different names which in turn
2208 may confuse the binder and the linker.
2211 .. index:: -nostdinc (gcc)
2214 Inhibit the search of the default location for the GNAT Run Time
2215 Library (RTL) source files.
2218 .. index:: -nostdlib (gcc)
2221 Inhibit the search of the default location for the GNAT Run Time
2222 Library (RTL) ALI files.
2228 ``n`` controls the optimization level:
2230 ======= ==================================================================
2232 ------- ------------------------------------------------------------------
2233 *0* No optimization, the default setting if no :switch:`-O` appears
2234 *1* Normal optimization, the default if you specify :switch:`-O` without an
2235 operand. A good compromise between code quality and compilation
2237 *2* Extensive optimization, may improve execution time, possibly at
2238 the cost of substantially increased compilation time.
2239 *3* Same as :switch:`-O2`, and also includes inline expansion for small
2240 subprograms in the same unit.
2241 *s* Optimize space usage
2242 ======= ==================================================================
2244 See also :ref:`Optimization_Levels`.
2247 .. index:: -pass-exit-codes (gcc)
2249 :switch:`-pass-exit-codes`
2250 Catch exit codes from the compiler and use the most meaningful as
2254 .. index:: --RTS (gcc)
2256 :switch:`--RTS={rts-path}`
2257 Specifies the default location of the run-time library. Same meaning as the
2258 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
2264 Used in place of :switch:`-c` to
2265 cause the assembler source file to be
2266 generated, using :file:`.s` as the extension,
2267 instead of the object file.
2268 This may be useful if you need to examine the generated assembly code.
2271 .. index:: -fverbose-asm (gcc)
2273 :switch:`-fverbose-asm`
2274 Used in conjunction with :switch:`-S`
2275 to cause the generated assembly code file to be annotated with variable
2276 names, making it significantly easier to follow.
2282 Show commands generated by the ``gcc`` driver. Normally used only for
2283 debugging purposes or if you need to be sure what version of the
2284 compiler you are executing.
2290 Execute ``ver`` version of the compiler. This is the ``gcc``
2291 version, not the GNAT version.
2297 Turn off warnings generated by the back end of the compiler. Use of
2298 this switch also causes the default for front end warnings to be set
2299 to suppress (as though :switch:`-gnatws` had appeared at the start of
2303 .. index:: Combining GNAT switches
2305 You may combine a sequence of GNAT switches into a single switch. For
2306 example, the combined switch
2312 is equivalent to specifying the following sequence of switches:
2316 -gnato -gnatf -gnati3
2318 The following restrictions apply to the combination of switches
2321 * The switch :switch:`-gnatc` if combined with other switches must come
2322 first in the string.
2324 * The switch :switch:`-gnats` if combined with other switches must come
2325 first in the string.
2328 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
2329 switches, and only one of them may appear in the command line.
2331 * The switch :switch:`-gnat-p` may not be combined with any other switch.
2333 * Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
2334 switch), then all further characters in the switch are interpreted
2335 as style modifiers (see description of :switch:`-gnaty`).
2337 * Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
2338 switch), then all further characters in the switch are interpreted
2339 as debug flags (see description of :switch:`-gnatd`).
2341 * Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
2342 switch), then all further characters in the switch are interpreted
2343 as warning mode modifiers (see description of :switch:`-gnatw`).
2345 * Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
2346 switch), then all further characters in the switch are interpreted
2347 as validity checking options (:ref:`Validity_Checking`).
2349 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2350 a combined list of options.
2352 .. _Output_and_Error_Message_Control:
2354 Output and Error Message Control
2355 --------------------------------
2359 The standard default format for error messages is called 'brief format'.
2360 Brief format messages are written to :file:`stderr` (the standard error
2361 file) and have the following form:
2365 e.adb:3:04: Incorrect spelling of keyword "function"
2366 e.adb:4:20: ";" should be "is"
2368 The first integer after the file name is the line number in the file,
2369 and the second integer is the column number within the line.
2370 ``GNAT Studio`` can parse the error messages
2371 and point to the referenced character.
2372 The following switches provide control over the error message
2376 .. index:: -gnatv (gcc)
2379 The ``v`` stands for verbose.
2380 The effect of this setting is to write long-format error
2381 messages to :file:`stdout` (the standard output file.
2382 The same program compiled with the
2383 :switch:`-gnatv` switch would generate:
2387 3. funcion X (Q : Integer)
2389 >>> Incorrect spelling of keyword "function"
2392 >>> ";" should be "is"
2395 The vertical bar indicates the location of the error, and the ``>>>``
2396 prefix can be used to search for error messages. When this switch is
2397 used the only source lines output are those with errors.
2400 .. index:: -gnatl (gcc)
2403 The ``l`` stands for list.
2404 This switch causes a full listing of
2405 the file to be generated. In the case where a body is
2406 compiled, the corresponding spec is also listed, along
2407 with any subunits. Typical output from compiling a package
2408 body :file:`p.adb` might look like::
2412 1. package body p is
2414 3. procedure a is separate;
2425 2. pragma Elaborate_Body
2446 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
2447 standard output is redirected, a brief summary is written to
2448 :file:`stderr` (standard error) giving the number of error messages and
2449 warning messages generated.
2452 .. index:: -gnatl=fname (gcc)
2454 :switch:`-gnatl={fname}`
2455 This has the same effect as :switch:`-gnatl` except that the output is
2456 written to a file instead of to standard output. If the given name
2457 :file:`fname` does not start with a period, then it is the full name
2458 of the file to be written. If :file:`fname` is an extension, it is
2459 appended to the name of the file being compiled. For example, if
2460 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
2461 then the output is written to file xyz.adb.lst.
2464 .. index:: -gnatU (gcc)
2467 This switch forces all error messages to be preceded by the unique
2468 string 'error:'. This means that error messages take a few more
2469 characters in space, but allows easy searching for and identification
2473 .. index:: -gnatb (gcc)
2476 The ``b`` stands for brief.
2477 This switch causes GNAT to generate the
2478 brief format error messages to :file:`stderr` (the standard error
2479 file) as well as the verbose
2480 format message or full listing (which as usual is written to
2481 :file:`stdout` (the standard output file).
2484 .. index:: -gnatm (gcc)
2486 :switch:`-gnatm={n}`
2487 The ``m`` stands for maximum.
2488 ``n`` is a decimal integer in the
2489 range of 1 to 999999 and limits the number of error or warning
2490 messages to be generated. For example, using
2491 :switch:`-gnatm2` might yield
2495 e.adb:3:04: Incorrect spelling of keyword "function"
2496 e.adb:5:35: missing ".."
2497 fatal error: maximum number of errors detected
2498 compilation abandoned
2501 The default setting if
2502 no switch is given is 9999. If the number of warnings reaches this
2503 limit, then a message is output and further warnings are suppressed,
2504 but the compilation is continued. If the number of error messages
2505 reaches this limit, then a message is output and the compilation
2506 is abandoned. A value of zero means that no limit applies.
2508 Note that the equal sign is optional, so the switches
2509 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
2512 .. index:: -gnatf (gcc)
2515 .. index:: Error messages, suppressing
2517 The ``f`` stands for full.
2518 Normally, the compiler suppresses error messages that are likely to be
2519 redundant. This switch causes all error
2520 messages to be generated. In particular, in the case of
2521 references to undefined variables. If a given variable is referenced
2522 several times, the normal format of messages is
2526 e.adb:7:07: "V" is undefined (more references follow)
2528 where the parenthetical comment warns that there are additional
2529 references to the variable ``V``. Compiling the same program with the
2530 :switch:`-gnatf` switch yields
2534 e.adb:7:07: "V" is undefined
2535 e.adb:8:07: "V" is undefined
2536 e.adb:8:12: "V" is undefined
2537 e.adb:8:16: "V" is undefined
2538 e.adb:9:07: "V" is undefined
2539 e.adb:9:12: "V" is undefined
2541 The :switch:`-gnatf` switch also generates additional information for
2542 some error messages. Some examples are:
2544 * Details on possibly non-portable unchecked conversion
2546 * List possible interpretations for ambiguous calls
2548 * Additional details on incorrect parameters
2551 .. index:: -gnatjnn (gcc)
2554 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
2555 with continuation lines are treated as though the continuation lines were
2556 separate messages (and so a warning with two continuation lines counts as
2557 three warnings, and is listed as three separate messages).
2559 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
2560 messages are output in a different manner. A message and all its continuation
2561 lines are treated as a unit, and count as only one warning or message in the
2562 statistics totals. Furthermore, the message is reformatted so that no line
2563 is longer than nn characters.
2566 .. index:: -gnatq (gcc)
2569 The ``q`` stands for quit (really 'don't quit').
2570 In normal operation mode, the compiler first parses the program and
2571 determines if there are any syntax errors. If there are, appropriate
2572 error messages are generated and compilation is immediately terminated.
2574 GNAT to continue with semantic analysis even if syntax errors have been
2575 found. This may enable the detection of more errors in a single run. On
2576 the other hand, the semantic analyzer is more likely to encounter some
2577 internal fatal error when given a syntactically invalid tree.
2580 .. index:: -gnatQ (gcc)
2583 In normal operation mode, the :file:`ALI` file is not generated if any
2584 illegalities are detected in the program. The use of :switch:`-gnatQ` forces
2585 generation of the :file:`ALI` file. This file is marked as being in
2586 error, so it cannot be used for binding purposes, but it does contain
2587 reasonably complete cross-reference information, and thus may be useful
2588 for use by tools (e.g., semantic browsing tools or integrated development
2589 environments) that are driven from the :file:`ALI` file. This switch
2590 implies :switch:`-gnatq`, since the semantic phase must be run to get a
2591 meaningful ALI file.
2593 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
2594 being in error, ``gnatmake`` will attempt to recompile the source when it
2595 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
2597 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
2598 since ALI files are never generated if :switch:`-gnats` is set.
2601 .. _Warning_Message_Control:
2603 Warning Message Control
2604 -----------------------
2606 .. index:: Warning messages
2608 In addition to error messages, which correspond to illegalities as defined
2609 in the Ada Reference Manual, the compiler detects two kinds of warning
2612 First, the compiler considers some constructs suspicious and generates a
2613 warning message to alert you to a possible error. Second, if the
2614 compiler detects a situation that is sure to raise an exception at
2615 run time, it generates a warning message. The following shows an example
2616 of warning messages:
2620 e.adb:4:24: warning: creation of object may raise Storage_Error
2621 e.adb:10:17: warning: static value out of range
2622 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2625 GNAT considers a large number of situations as appropriate
2626 for the generation of warning messages. As always, warnings are not
2627 definite indications of errors. For example, if you do an out-of-range
2628 assignment with the deliberate intention of raising a
2629 ``Constraint_Error`` exception, then the warning that may be
2630 issued does not indicate an error. Some of the situations for which GNAT
2631 issues warnings (at least some of the time) are given in the following
2632 list. This list is not complete, and new warnings are often added to
2633 subsequent versions of GNAT. The list is intended to give a general idea
2634 of the kinds of warnings that are generated.
2636 * Possible infinitely recursive calls
2638 * Out-of-range values being assigned
2640 * Possible order of elaboration problems
2642 * Size not a multiple of alignment for a record type
2644 * Assertions (pragma Assert) that are sure to fail
2648 * Address clauses with possibly unaligned values, or where an attempt is
2649 made to overlay a smaller variable with a larger one.
2651 * Fixed-point type declarations with a null range
2653 * Direct_IO or Sequential_IO instantiated with a type that has access values
2655 * Variables that are never assigned a value
2657 * Variables that are referenced before being initialized
2659 * Task entries with no corresponding ``accept`` statement
2661 * Duplicate accepts for the same task entry in a ``select``
2663 * Objects that take too much storage
2665 * Unchecked conversion between types of differing sizes
2667 * Missing ``return`` statement along some execution path in a function
2669 * Incorrect (unrecognized) pragmas
2671 * Incorrect external names
2673 * Allocation from empty storage pool
2675 * Potentially blocking operation in protected type
2677 * Suspicious parenthesization of expressions
2679 * Mismatching bounds in an aggregate
2681 * Attempt to return local value by reference
2683 * Premature instantiation of a generic body
2685 * Attempt to pack aliased components
2687 * Out of bounds array subscripts
2689 * Wrong length on string assignment
2691 * Violations of style rules if style checking is enabled
2693 * Unused |with| clauses
2695 * ``Bit_Order`` usage that does not have any effect
2697 * ``Standard.Duration`` used to resolve universal fixed expression
2699 * Dereference of possibly null value
2701 * Declaration that is likely to cause storage error
2703 * Internal GNAT unit |withed| by application unit
2705 * Values known to be out of range at compile time
2707 * Unreferenced or unmodified variables. Note that a special
2708 exemption applies to variables which contain any of the substrings
2709 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
2710 are considered likely to be intentionally used in a situation where
2711 otherwise a warning would be given, so warnings of this kind are
2712 always suppressed for such variables.
2714 * Address overlays that could clobber memory
2716 * Unexpected initialization when address clause present
2718 * Bad alignment for address clause
2720 * Useless type conversions
2722 * Redundant assignment statements and other redundant constructs
2724 * Useless exception handlers
2726 * Accidental hiding of name by child unit
2728 * Access before elaboration detected at compile time
2730 * A range in a ``for`` loop that is known to be null or might be null
2733 The following section lists compiler switches that are available
2734 to control the handling of warning messages. It is also possible
2735 to exercise much finer control over what warnings are issued and
2736 suppressed using the GNAT pragma Warnings (see the description
2737 of the pragma in the :title:`GNAT_Reference_manual`).
2740 .. index:: -gnatwa (gcc)
2743 *Activate most optional warnings.*
2745 This switch activates most optional warning messages. See the remaining list
2746 in this section for details on optional warning messages that can be
2747 individually controlled. The warnings that are not turned on by this
2751 * :switch:`-gnatwd` (implicit dereferencing)
2753 * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
2755 * :switch:`-gnatwh` (hiding)
2757 * :switch:`-gnatw.h` (holes in record layouts)
2759 * :switch:`-gnatw.j` (late primitives of tagged types)
2761 * :switch:`-gnatw.k` (redefinition of names in standard)
2763 * :switch:`-gnatwl` (elaboration warnings)
2765 * :switch:`-gnatw.l` (inherited aspects)
2767 * :switch:`-gnatw.n` (atomic synchronization)
2769 * :switch:`-gnatwo` (address clause overlay)
2771 * :switch:`-gnatw.o` (values set by out parameters ignored)
2773 * :switch:`-gnatw.q` (questionable layout of record types)
2775 * :switch:`-gnatw_r` (out-of-order record representation clauses)
2777 * :switch:`-gnatw.s` (overridden size clause)
2779 * :switch:`-gnatwt` (tracking of deleted conditional code)
2781 * :switch:`-gnatw.u` (unordered enumeration)
2783 * :switch:`-gnatw.w` (use of Warnings Off)
2785 * :switch:`-gnatw.y` (reasons for package needing body)
2787 All other optional warnings are turned on.
2790 .. index:: -gnatwA (gcc)
2793 *Suppress all optional errors.*
2795 This switch suppresses all optional warning messages, see remaining list
2796 in this section for details on optional warning messages that can be
2797 individually controlled. Note that unlike switch :switch:`-gnatws`, the
2798 use of switch :switch:`-gnatwA` does not suppress warnings that are
2799 normally given unconditionally and cannot be individually controlled
2800 (for example, the warning about a missing exit path in a function).
2801 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
2802 the use of switch :switch:`-gnatwA` can be individually turned back
2803 on. For example the use of switch :switch:`-gnatwA` followed by
2804 switch :switch:`-gnatwd` will suppress all optional warnings except
2805 the warnings for implicit dereferencing.
2807 .. index:: -gnatw.a (gcc)
2810 *Activate warnings on failing assertions.*
2812 .. index:: Assert failures
2814 This switch activates warnings for assertions where the compiler can tell at
2815 compile time that the assertion will fail. Note that this warning is given
2816 even if assertions are disabled. The default is that such warnings are
2820 .. index:: -gnatw.A (gcc)
2823 *Suppress warnings on failing assertions.*
2825 .. index:: Assert failures
2827 This switch suppresses warnings for assertions where the compiler can tell at
2828 compile time that the assertion will fail.
2834 *Activate warnings on anonymous allocators.*
2836 .. index:: Anonymous allocators
2838 This switch activates warnings for allocators of anonymous access types,
2839 which can involve run-time accessibility checks and lead to unexpected
2840 accessibility violations. For more details on the rules involved, see
2847 *Supress warnings on anonymous allocators.*
2849 .. index:: Anonymous allocators
2851 This switch suppresses warnings for anonymous access type allocators.
2854 .. index:: -gnatwb (gcc)
2857 *Activate warnings on bad fixed values.*
2859 .. index:: Bad fixed values
2861 .. index:: Fixed-point Small value
2863 .. index:: Small value
2865 This switch activates warnings for static fixed-point expressions whose
2866 value is not an exact multiple of Small. Such values are implementation
2867 dependent, since an implementation is free to choose either of the multiples
2868 that surround the value. GNAT always chooses the closer one, but this is not
2869 required behavior, and it is better to specify a value that is an exact
2870 multiple, ensuring predictable execution. The default is that such warnings
2874 .. index:: -gnatwB (gcc)
2877 *Suppress warnings on bad fixed values.*
2879 This switch suppresses warnings for static fixed-point expressions whose
2880 value is not an exact multiple of Small.
2883 .. index:: -gnatw.b (gcc)
2886 *Activate warnings on biased representation.*
2888 .. index:: Biased representation
2890 This switch activates warnings when a size clause, value size clause, component
2891 clause, or component size clause forces the use of biased representation for an
2892 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2893 to represent 10/11). The default is that such warnings are generated.
2896 .. index:: -gnatwB (gcc)
2899 *Suppress warnings on biased representation.*
2901 This switch suppresses warnings for representation clauses that force the use
2902 of biased representation.
2905 .. index:: -gnatwc (gcc)
2908 *Activate warnings on conditionals.*
2910 .. index:: Conditionals, constant
2912 This switch activates warnings for conditional expressions used in
2913 tests that are known to be True or False at compile time. The default
2914 is that such warnings are not generated.
2915 Note that this warning does
2916 not get issued for the use of boolean variables or constants whose
2917 values are known at compile time, since this is a standard technique
2918 for conditional compilation in Ada, and this would generate too many
2919 false positive warnings.
2921 This warning option also activates a special test for comparisons using
2922 the operators '>=' and' <='.
2923 If the compiler can tell that only the equality condition is possible,
2924 then it will warn that the '>' or '<' part of the test
2925 is useless and that the operator could be replaced by '='.
2926 An example would be comparing a ``Natural`` variable <= 0.
2928 This warning option also generates warnings if
2929 one or both tests is optimized away in a membership test for integer
2930 values if the result can be determined at compile time. Range tests on
2931 enumeration types are not included, since it is common for such tests
2932 to include an end point.
2934 This warning can also be turned on using :switch:`-gnatwa`.
2937 .. index:: -gnatwC (gcc)
2940 *Suppress warnings on conditionals.*
2942 This switch suppresses warnings for conditional expressions used in
2943 tests that are known to be True or False at compile time.
2946 .. index:: -gnatw.c (gcc)
2949 *Activate warnings on missing component clauses.*
2951 .. index:: Component clause, missing
2953 This switch activates warnings for record components where a record
2954 representation clause is present and has component clauses for the
2955 majority, but not all, of the components. A warning is given for each
2956 component for which no component clause is present.
2959 .. index:: -gnatw.C (gcc)
2962 *Suppress warnings on missing component clauses.*
2964 This switch suppresses warnings for record components that are
2965 missing a component clause in the situation described above.
2968 .. index:: -gnatw_c (gcc)
2971 *Activate warnings on unknown condition in Compile_Time_Warning.*
2973 .. index:: Compile_Time_Warning
2974 .. index:: Compile_Time_Error
2976 This switch activates warnings on a pragma Compile_Time_Warning
2977 or Compile_Time_Error whose condition has a value that is not
2978 known at compile time.
2979 The default is that such warnings are generated.
2982 .. index:: -gnatw_C (gcc)
2985 *Suppress warnings on unknown condition in Compile_Time_Warning.*
2987 This switch supresses warnings on a pragma Compile_Time_Warning
2988 or Compile_Time_Error whose condition has a value that is not
2989 known at compile time.
2992 .. index:: -gnatwd (gcc)
2995 *Activate warnings on implicit dereferencing.*
2997 If this switch is set, then the use of a prefix of an access type
2998 in an indexed component, slice, or selected component without an
2999 explicit ``.all`` will generate a warning. With this warning
3000 enabled, access checks occur only at points where an explicit
3001 ``.all`` appears in the source code (assuming no warnings are
3002 generated as a result of this switch). The default is that such
3003 warnings are not generated.
3006 .. index:: -gnatwD (gcc)
3009 *Suppress warnings on implicit dereferencing.*
3011 .. index:: Implicit dereferencing
3013 .. index:: Dereferencing, implicit
3015 This switch suppresses warnings for implicit dereferences in
3016 indexed components, slices, and selected components.
3019 .. index:: -gnatw.d (gcc)
3022 *Activate tagging of warning and info messages.*
3024 If this switch is set, then warning messages are tagged, with one of the
3028 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
3033 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
3038 Used to tag elaboration information (info) messages generated when the
3039 static model of elaboration is used and the :switch:`-gnatel` switch is set.
3042 - *[restriction warning]*
3043 Used to tag warning messages for restriction violations, activated by use
3044 of the pragma ``Restriction_Warnings``.
3047 - *[warning-as-error]*
3048 Used to tag warning messages that have been converted to error messages by
3049 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
3050 the string "error: " rather than "warning: ".
3053 - *[enabled by default]*
3054 Used to tag all other warnings that are always given by default, unless
3055 warnings are completely suppressed using pragma *Warnings(Off)* or
3056 the switch :switch:`-gnatws`.
3060 .. index:: -gnatw.d (gcc)
3063 *Deactivate tagging of warning and info messages messages.*
3065 If this switch is set, then warning messages return to the default
3066 mode in which warnings and info messages are not tagged as described above for
3070 .. index:: -gnatwe (gcc)
3071 .. index:: Warnings, treat as error
3074 *Treat warnings and style checks as errors.*
3076 This switch causes warning messages and style check messages to be
3078 The warning string still appears, but the warning messages are counted
3079 as errors, and prevent the generation of an object file. Note that this
3080 is the only -gnatw switch that affects the handling of style check messages.
3081 Note also that this switch has no effect on info (information) messages, which
3082 are not treated as errors if this switch is present.
3085 .. index:: -gnatw.e (gcc)
3088 *Activate every optional warning.*
3090 .. index:: Warnings, activate every optional warning
3092 This switch activates all optional warnings, including those which
3093 are not activated by :switch:`-gnatwa`. The use of this switch is not
3094 recommended for normal use. If you turn this switch on, it is almost
3095 certain that you will get large numbers of useless warnings. The
3096 warnings that are excluded from :switch:`-gnatwa` are typically highly
3097 specialized warnings that are suitable for use only in code that has
3098 been specifically designed according to specialized coding rules.
3101 .. index:: -gnatwE (gcc)
3102 .. index:: Warnings, treat as error
3105 *Treat all run-time exception warnings as errors.*
3107 This switch causes warning messages regarding errors that will be raised
3108 during run-time execution to be treated as errors.
3111 .. index:: -gnatwf (gcc)
3114 *Activate warnings on unreferenced formals.*
3116 .. index:: Formals, unreferenced
3118 This switch causes a warning to be generated if a formal parameter
3119 is not referenced in the body of the subprogram. This warning can
3120 also be turned on using :switch:`-gnatwu`. The
3121 default is that these warnings are not generated.
3124 .. index:: -gnatwF (gcc)
3127 *Suppress warnings on unreferenced formals.*
3129 This switch suppresses warnings for unreferenced formal
3130 parameters. Note that the
3131 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
3132 effect of warning on unreferenced entities other than subprogram
3136 .. index:: -gnatwg (gcc)
3139 *Activate warnings on unrecognized pragmas.*
3141 .. index:: Pragmas, unrecognized
3143 This switch causes a warning to be generated if an unrecognized
3144 pragma is encountered. Apart from issuing this warning, the
3145 pragma is ignored and has no effect. The default
3146 is that such warnings are issued (satisfying the Ada Reference
3147 Manual requirement that such warnings appear).
3150 .. index:: -gnatwG (gcc)
3153 *Suppress warnings on unrecognized pragmas.*
3155 This switch suppresses warnings for unrecognized pragmas.
3158 .. index:: -gnatw.g (gcc)
3161 *Warnings used for GNAT sources.*
3163 This switch sets the warning categories that are used by the standard
3164 GNAT style. Currently this is equivalent to
3165 :switch:`-gnatwAao.q.s.CI.V.X.Z`
3166 but more warnings may be added in the future without advanced notice.
3169 .. index:: -gnatwh (gcc)
3172 *Activate warnings on hiding.*
3174 .. index:: Hiding of Declarations
3176 This switch activates warnings on hiding declarations that are considered
3177 potentially confusing. Not all cases of hiding cause warnings; for example an
3178 overriding declaration hides an implicit declaration, which is just normal
3179 code. The default is that warnings on hiding are not generated.
3182 .. index:: -gnatwH (gcc)
3185 *Suppress warnings on hiding.*
3187 This switch suppresses warnings on hiding declarations.
3190 .. index:: -gnatw.h (gcc)
3193 *Activate warnings on holes/gaps in records.*
3195 .. index:: Record Representation (gaps)
3197 This switch activates warnings on component clauses in record
3198 representation clauses that leave holes (gaps) in the record layout.
3199 If this warning option is active, then record representation clauses
3200 should specify a contiguous layout, adding unused fill fields if needed.
3203 .. index:: -gnatw.H (gcc)
3206 *Suppress warnings on holes/gaps in records.*
3208 This switch suppresses warnings on component clauses in record
3209 representation clauses that leave holes (haps) in the record layout.
3212 .. index:: -gnatwi (gcc)
3215 *Activate warnings on implementation units.*
3217 This switch activates warnings for a |with| of an internal GNAT
3218 implementation unit, defined as any unit from the ``Ada``,
3219 ``Interfaces``, ``GNAT``,
3221 hierarchies that is not
3222 documented in either the Ada Reference Manual or the GNAT
3223 Programmer's Reference Manual. Such units are intended only
3224 for internal implementation purposes and should not be |withed|
3225 by user programs. The default is that such warnings are generated
3228 .. index:: -gnatwI (gcc)
3231 *Disable warnings on implementation units.*
3233 This switch disables warnings for a |with| of an internal GNAT
3234 implementation unit.
3237 .. index:: -gnatw.i (gcc)
3240 *Activate warnings on overlapping actuals.*
3242 This switch enables a warning on statically detectable overlapping actuals in
3243 a subprogram call, when one of the actuals is an in-out parameter, and the
3244 types of the actuals are not by-copy types. This warning is off by default.
3247 .. index:: -gnatw.I (gcc)
3250 *Disable warnings on overlapping actuals.*
3252 This switch disables warnings on overlapping actuals in a call..
3255 .. index:: -gnatwj (gcc)
3258 *Activate warnings on obsolescent features (Annex J).*
3260 .. index:: Features, obsolescent
3262 .. index:: Obsolescent features
3264 If this warning option is activated, then warnings are generated for
3265 calls to subprograms marked with ``pragma Obsolescent`` and
3266 for use of features in Annex J of the Ada Reference Manual. In the
3267 case of Annex J, not all features are flagged. In particular use
3268 of the renamed packages (like ``Text_IO``) and use of package
3269 ``ASCII`` are not flagged, since these are very common and
3270 would generate many annoying positive warnings. The default is that
3271 such warnings are not generated.
3273 In addition to the above cases, warnings are also generated for
3274 GNAT features that have been provided in past versions but which
3275 have been superseded (typically by features in the new Ada standard).
3276 For example, ``pragma Ravenscar`` will be flagged since its
3277 function is replaced by ``pragma Profile(Ravenscar)``, and
3278 ``pragma Interface_Name`` will be flagged since its function
3279 is replaced by ``pragma Import``.
3281 Note that this warning option functions differently from the
3282 restriction ``No_Obsolescent_Features`` in two respects.
3283 First, the restriction applies only to annex J features.
3284 Second, the restriction does flag uses of package ``ASCII``.
3287 .. index:: -gnatwJ (gcc)
3290 *Suppress warnings on obsolescent features (Annex J).*
3292 This switch disables warnings on use of obsolescent features.
3295 .. index:: -gnatw.j (gcc)
3298 *Activate warnings on late declarations of tagged type primitives.*
3300 This switch activates warnings on visible primitives added to a
3301 tagged type after deriving a private extension from it.
3304 .. index:: -gnatw.J (gcc)
3307 *Suppress warnings on late declarations of tagged type primitives.*
3309 This switch suppresses warnings on visible primitives added to a
3310 tagged type after deriving a private extension from it.
3313 .. index:: -gnatwk (gcc)
3316 *Activate warnings on variables that could be constants.*
3318 This switch activates warnings for variables that are initialized but
3319 never modified, and then could be declared constants. The default is that
3320 such warnings are not given.
3323 .. index:: -gnatwK (gcc)
3326 *Suppress warnings on variables that could be constants.*
3328 This switch disables warnings on variables that could be declared constants.
3331 .. index:: -gnatw.k (gcc)
3334 *Activate warnings on redefinition of names in standard.*
3336 This switch activates warnings for declarations that declare a name that
3337 is defined in package Standard. Such declarations can be confusing,
3338 especially since the names in package Standard continue to be directly
3339 visible, meaning that use visibiliy on such redeclared names does not
3340 work as expected. Names of discriminants and components in records are
3341 not included in this check.
3344 .. index:: -gnatwK (gcc)
3347 *Suppress warnings on redefinition of names in standard.*
3349 This switch activates warnings for declarations that declare a name that
3350 is defined in package Standard.
3353 .. index:: -gnatwl (gcc)
3356 *Activate warnings for elaboration pragmas.*
3358 .. index:: Elaboration, warnings
3360 This switch activates warnings for possible elaboration problems,
3361 including suspicious use
3362 of ``Elaborate`` pragmas, when using the static elaboration model, and
3363 possible situations that may raise ``Program_Error`` when using the
3364 dynamic elaboration model.
3365 See the section in this guide on elaboration checking for further details.
3366 The default is that such warnings
3370 .. index:: -gnatwL (gcc)
3373 *Suppress warnings for elaboration pragmas.*
3375 This switch suppresses warnings for possible elaboration problems.
3378 .. index:: -gnatw.l (gcc)
3381 *List inherited aspects.*
3383 This switch causes the compiler to list inherited invariants,
3384 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3385 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3388 .. index:: -gnatw.L (gcc)
3391 *Suppress listing of inherited aspects.*
3393 This switch suppresses listing of inherited aspects.
3396 .. index:: -gnatwm (gcc)
3399 *Activate warnings on modified but unreferenced variables.*
3401 This switch activates warnings for variables that are assigned (using
3402 an initialization value or with one or more assignment statements) but
3403 whose value is never read. The warning is suppressed for volatile
3404 variables and also for variables that are renamings of other variables
3405 or for which an address clause is given.
3406 The default is that these warnings are not given.
3409 .. index:: -gnatwM (gcc)
3412 *Disable warnings on modified but unreferenced variables.*
3414 This switch disables warnings for variables that are assigned or
3415 initialized, but never read.
3418 .. index:: -gnatw.m (gcc)
3421 *Activate warnings on suspicious modulus values.*
3423 This switch activates warnings for modulus values that seem suspicious.
3424 The cases caught are where the size is the same as the modulus (e.g.
3425 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3426 with no size clause. The guess in both cases is that 2**x was intended
3427 rather than x. In addition expressions of the form 2*x for small x
3428 generate a warning (the almost certainly accurate guess being that
3429 2**x was intended). The default is that these warnings are given.
3432 .. index:: -gnatw.M (gcc)
3435 *Disable warnings on suspicious modulus values.*
3437 This switch disables warnings for suspicious modulus values.
3440 .. index:: -gnatwn (gcc)
3443 *Set normal warnings mode.*
3445 This switch sets normal warning mode, in which enabled warnings are
3446 issued and treated as warnings rather than errors. This is the default
3447 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
3448 an explicit :switch:`-gnatws` or
3449 :switch:`-gnatwe`. It also cancels the effect of the
3450 implicit :switch:`-gnatwe` that is activated by the
3451 use of :switch:`-gnatg`.
3454 .. index:: -gnatw.n (gcc)
3455 .. index:: Atomic Synchronization, warnings
3458 *Activate warnings on atomic synchronization.*
3460 This switch actives warnings when an access to an atomic variable
3461 requires the generation of atomic synchronization code. These
3462 warnings are off by default.
3464 .. index:: -gnatw.N (gcc)
3467 *Suppress warnings on atomic synchronization.*
3469 .. index:: Atomic Synchronization, warnings
3471 This switch suppresses warnings when an access to an atomic variable
3472 requires the generation of atomic synchronization code.
3475 .. index:: -gnatwo (gcc)
3476 .. index:: Address Clauses, warnings
3479 *Activate warnings on address clause overlays.*
3481 This switch activates warnings for possibly unintended initialization
3482 effects of defining address clauses that cause one variable to overlap
3483 another. The default is that such warnings are generated.
3486 .. index:: -gnatwO (gcc)
3489 *Suppress warnings on address clause overlays.*
3491 This switch suppresses warnings on possibly unintended initialization
3492 effects of defining address clauses that cause one variable to overlap
3496 .. index:: -gnatw.o (gcc)
3499 *Activate warnings on modified but unreferenced out parameters.*
3501 This switch activates warnings for variables that are modified by using
3502 them as actuals for a call to a procedure with an out mode formal, where
3503 the resulting assigned value is never read. It is applicable in the case
3504 where there is more than one out mode formal. If there is only one out
3505 mode formal, the warning is issued by default (controlled by -gnatwu).
3506 The warning is suppressed for volatile
3507 variables and also for variables that are renamings of other variables
3508 or for which an address clause is given.
3509 The default is that these warnings are not given.
3512 .. index:: -gnatw.O (gcc)
3515 *Disable warnings on modified but unreferenced out parameters.*
3517 This switch suppresses warnings for variables that are modified by using
3518 them as actuals for a call to a procedure with an out mode formal, where
3519 the resulting assigned value is never read.
3522 .. index:: -gnatwp (gcc)
3523 .. index:: Inlining, warnings
3526 *Activate warnings on ineffective pragma Inlines.*
3528 This switch activates warnings for failure of front end inlining
3529 (activated by :switch:`-gnatN`) to inline a particular call. There are
3530 many reasons for not being able to inline a call, including most
3531 commonly that the call is too complex to inline. The default is
3532 that such warnings are not given.
3533 Warnings on ineffective inlining by the gcc back-end can be activated
3534 separately, using the gcc switch -Winline.
3537 .. index:: -gnatwP (gcc)
3540 *Suppress warnings on ineffective pragma Inlines.*
3542 This switch suppresses warnings on ineffective pragma Inlines. If the
3543 inlining mechanism cannot inline a call, it will simply ignore the
3547 .. index:: -gnatw.p (gcc)
3548 .. index:: Parameter order, warnings
3551 *Activate warnings on parameter ordering.*
3553 This switch activates warnings for cases of suspicious parameter
3554 ordering when the list of arguments are all simple identifiers that
3555 match the names of the formals, but are in a different order. The
3556 warning is suppressed if any use of named parameter notation is used,
3557 so this is the appropriate way to suppress a false positive (and
3558 serves to emphasize that the "misordering" is deliberate). The
3559 default is that such warnings are not given.
3562 .. index:: -gnatw.P (gcc)
3565 *Suppress warnings on parameter ordering.*
3567 This switch suppresses warnings on cases of suspicious parameter
3571 .. index:: -gnatwq (gcc)
3572 .. index:: Parentheses, warnings
3575 *Activate warnings on questionable missing parentheses.*
3577 This switch activates warnings for cases where parentheses are not used and
3578 the result is potential ambiguity from a readers point of view. For example
3579 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3580 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3581 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3582 follow the rule of always parenthesizing to make the association clear, and
3583 this warning switch warns if such parentheses are not present. The default
3584 is that these warnings are given.
3587 .. index:: -gnatwQ (gcc)
3590 *Suppress warnings on questionable missing parentheses.*
3592 This switch suppresses warnings for cases where the association is not
3593 clear and the use of parentheses is preferred.
3596 .. index:: -gnatw.q (gcc)
3597 .. index:: Layout, warnings
3600 *Activate warnings on questionable layout of record types.*
3602 This switch activates warnings for cases where the default layout of
3603 a record type, that is to say the layout of its components in textual
3604 order of the source code, would very likely cause inefficiencies in
3605 the code generated by the compiler, both in terms of space and speed
3606 during execution. One warning is issued for each problematic component
3607 without representation clause in the nonvariant part and then in each
3608 variant recursively, if any.
3610 The purpose of these warnings is neither to prescribe an optimal layout
3611 nor to force the use of representation clauses, but rather to get rid of
3612 the most blatant inefficiencies in the layout. Therefore, the default
3613 layout is matched against the following synthetic ordered layout and
3614 the deviations are flagged on a component-by-component basis:
3616 * first all components or groups of components whose length is fixed
3617 and a multiple of the storage unit,
3619 * then the remaining components whose length is fixed and not a multiple
3620 of the storage unit,
3622 * then the remaining components whose length doesn't depend on discriminants
3623 (that is to say, with variable but uniform length for all objects),
3625 * then all components whose length depends on discriminants,
3627 * finally the variant part (if any),
3629 for the nonvariant part and for each variant recursively, if any.
3631 The exact wording of the warning depends on whether the compiler is allowed
3632 to reorder the components in the record type or precluded from doing it by
3633 means of pragma ``No_Component_Reordering``.
3635 The default is that these warnings are not given.
3637 .. index:: -gnatw.Q (gcc)
3640 *Suppress warnings on questionable layout of record types.*
3642 This switch suppresses warnings for cases where the default layout of
3643 a record type would very likely cause inefficiencies.
3646 .. index:: -gnatwr (gcc)
3649 *Activate warnings on redundant constructs.*
3651 This switch activates warnings for redundant constructs. The following
3652 is the current list of constructs regarded as redundant:
3654 * Assignment of an item to itself.
3656 * Type conversion that converts an expression to its own type.
3658 * Use of the attribute ``Base`` where ``typ'Base`` is the same
3661 * Use of pragma ``Pack`` when all components are placed by a record
3662 representation clause.
3664 * Exception handler containing only a reraise statement (raise with no
3665 operand) which has no effect.
3667 * Use of the operator abs on an operand that is known at compile time
3670 * Comparison of an object or (unary or binary) operation of boolean type to
3671 an explicit True value.
3673 The default is that warnings for redundant constructs are not given.
3676 .. index:: -gnatwR (gcc)
3679 *Suppress warnings on redundant constructs.*
3681 This switch suppresses warnings for redundant constructs.
3684 .. index:: -gnatw.r (gcc)
3687 *Activate warnings for object renaming function.*
3689 This switch activates warnings for an object renaming that renames a
3690 function call, which is equivalent to a constant declaration (as
3691 opposed to renaming the function itself). The default is that these
3695 .. index:: -gnatw.R (gcc)
3698 *Suppress warnings for object renaming function.*
3700 This switch suppresses warnings for object renaming function.
3703 .. index:: -gnatw_r (gcc)
3706 *Activate warnings for out-of-order record representation clauses.*
3708 This switch activates warnings for record representation clauses,
3709 if the order of component declarations, component clauses,
3710 and bit-level layout do not all agree.
3711 The default is that these warnings are not given.
3714 .. index:: -gnatw_R (gcc)
3717 *Suppress warnings for out-of-order record representation clauses.*
3720 .. index:: -gnatws (gcc)
3723 *Suppress all warnings.*
3725 This switch completely suppresses the
3726 output of all warning messages from the GNAT front end, including
3727 both warnings that can be controlled by switches described in this
3728 section, and those that are normally given unconditionally. The
3729 effect of this suppress action can only be cancelled by a subsequent
3730 use of the switch :switch:`-gnatwn`.
3732 Note that switch :switch:`-gnatws` does not suppress
3733 warnings from the ``gcc`` back end.
3734 To suppress these back end warnings as well, use the switch :switch:`-w`
3735 in addition to :switch:`-gnatws`. Also this switch has no effect on the
3736 handling of style check messages.
3739 .. index:: -gnatw.s (gcc)
3740 .. index:: Record Representation (component sizes)
3743 *Activate warnings on overridden size clauses.*
3745 This switch activates warnings on component clauses in record
3746 representation clauses where the length given overrides that
3747 specified by an explicit size clause for the component type. A
3748 warning is similarly given in the array case if a specified
3749 component size overrides an explicit size clause for the array
3753 .. index:: -gnatw.S (gcc)
3756 *Suppress warnings on overridden size clauses.*
3758 This switch suppresses warnings on component clauses in record
3759 representation clauses that override size clauses, and similar
3760 warnings when an array component size overrides a size clause.
3763 .. index:: -gnatwt (gcc)
3764 .. index:: Deactivated code, warnings
3765 .. index:: Deleted code, warnings
3768 *Activate warnings for tracking of deleted conditional code.*
3770 This switch activates warnings for tracking of code in conditionals (IF and
3771 CASE statements) that is detected to be dead code which cannot be executed, and
3772 which is removed by the front end. This warning is off by default. This may be
3773 useful for detecting deactivated code in certified applications.
3776 .. index:: -gnatwT (gcc)
3779 *Suppress warnings for tracking of deleted conditional code.*
3781 This switch suppresses warnings for tracking of deleted conditional code.
3784 .. index:: -gnatw.t (gcc)
3787 *Activate warnings on suspicious contracts.*
3789 This switch activates warnings on suspicious contracts. This includes
3790 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
3791 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3792 ``Contract_Cases``). A function postcondition or contract case is suspicious
3793 when no postcondition or contract case for this function mentions the result
3794 of the function. A procedure postcondition or contract case is suspicious
3795 when it only refers to the pre-state of the procedure, because in that case
3796 it should rather be expressed as a precondition. This switch also controls
3797 warnings on suspicious cases of expressions typically found in contracts like
3798 quantified expressions and uses of Update attribute. The default is that such
3799 warnings are generated.
3802 .. index:: -gnatw.T (gcc)
3805 *Suppress warnings on suspicious contracts.*
3807 This switch suppresses warnings on suspicious contracts.
3810 .. index:: -gnatwu (gcc)
3813 *Activate warnings on unused entities.*
3815 This switch activates warnings to be generated for entities that
3816 are declared but not referenced, and for units that are |withed|
3818 referenced. In the case of packages, a warning is also generated if
3819 no entities in the package are referenced. This means that if a with'ed
3820 package is referenced but the only references are in ``use``
3821 clauses or ``renames``
3822 declarations, a warning is still generated. A warning is also generated
3823 for a generic package that is |withed| but never instantiated.
3824 In the case where a package or subprogram body is compiled, and there
3825 is a |with| on the corresponding spec
3826 that is only referenced in the body,
3827 a warning is also generated, noting that the
3828 |with| can be moved to the body. The default is that
3829 such warnings are not generated.
3830 This switch also activates warnings on unreferenced formals
3831 (it includes the effect of :switch:`-gnatwf`).
3834 .. index:: -gnatwU (gcc)
3837 *Suppress warnings on unused entities.*
3839 This switch suppresses warnings for unused entities and packages.
3840 It also turns off warnings on unreferenced formals (and thus includes
3841 the effect of :switch:`-gnatwF`).
3844 .. index:: -gnatw.u (gcc)
3847 *Activate warnings on unordered enumeration types.*
3849 This switch causes enumeration types to be considered as conceptually
3850 unordered, unless an explicit pragma ``Ordered`` is given for the type.
3851 The effect is to generate warnings in clients that use explicit comparisons
3852 or subranges, since these constructs both treat objects of the type as
3853 ordered. (A *client* is defined as a unit that is other than the unit in
3854 which the type is declared, or its body or subunits.) Please refer to
3855 the description of pragma ``Ordered`` in the
3856 :title:`GNAT Reference Manual` for further details.
3857 The default is that such warnings are not generated.
3860 .. index:: -gnatw.U (gcc)
3863 *Deactivate warnings on unordered enumeration types.*
3865 This switch causes all enumeration types to be considered as ordered, so
3866 that no warnings are given for comparisons or subranges for any type.
3869 .. index:: -gnatwv (gcc)
3870 .. index:: Unassigned variable warnings
3873 *Activate warnings on unassigned variables.*
3875 This switch activates warnings for access to variables which
3876 may not be properly initialized. The default is that
3877 such warnings are generated.
3880 .. index:: -gnatwV (gcc)
3883 *Suppress warnings on unassigned variables.*
3885 This switch suppresses warnings for access to variables which
3886 may not be properly initialized.
3887 For variables of a composite type, the warning can also be suppressed in
3888 Ada 2005 by using a default initialization with a box. For example, if
3889 Table is an array of records whose components are only partially uninitialized,
3890 then the following code:
3894 Tab : Table := (others => <>);
3896 will suppress warnings on subsequent statements that access components
3900 .. index:: -gnatw.v (gcc)
3901 .. index:: bit order warnings
3904 *Activate info messages for non-default bit order.*
3906 This switch activates messages (labeled "info", they are not warnings,
3907 just informational messages) about the effects of non-default bit-order
3908 on records to which a component clause is applied. The effect of specifying
3909 non-default bit ordering is a bit subtle (and changed with Ada 2005), so
3910 these messages, which are given by default, are useful in understanding the
3911 exact consequences of using this feature.
3914 .. index:: -gnatw.V (gcc)
3917 *Suppress info messages for non-default bit order.*
3919 This switch suppresses information messages for the effects of specifying
3920 non-default bit order on record components with component clauses.
3923 .. index:: -gnatww (gcc)
3924 .. index:: String indexing warnings
3927 *Activate warnings on wrong low bound assumption.*
3929 This switch activates warnings for indexing an unconstrained string parameter
3930 with a literal or S'Length. This is a case where the code is assuming that the
3931 low bound is one, which is in general not true (for example when a slice is
3932 passed). The default is that such warnings are generated.
3935 .. index:: -gnatwW (gcc)
3938 *Suppress warnings on wrong low bound assumption.*
3940 This switch suppresses warnings for indexing an unconstrained string parameter
3941 with a literal or S'Length. Note that this warning can also be suppressed
3942 in a particular case by adding an assertion that the lower bound is 1,
3943 as shown in the following example:
3947 procedure K (S : String) is
3948 pragma Assert (S'First = 1);
3952 .. index:: -gnatw.w (gcc)
3953 .. index:: Warnings Off control
3956 *Activate warnings on Warnings Off pragmas.*
3958 This switch activates warnings for use of ``pragma Warnings (Off, entity)``
3959 where either the pragma is entirely useless (because it suppresses no
3960 warnings), or it could be replaced by ``pragma Unreferenced`` or
3961 ``pragma Unmodified``.
3962 Also activates warnings for the case of
3963 Warnings (Off, String), where either there is no matching
3964 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
3965 The default is that these warnings are not given.
3968 .. index:: -gnatw.W (gcc)
3971 *Suppress warnings on unnecessary Warnings Off pragmas.*
3973 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
3976 .. index:: -gnatwx (gcc)
3977 .. index:: Export/Import pragma warnings
3980 *Activate warnings on Export/Import pragmas.*
3982 This switch activates warnings on Export/Import pragmas when
3983 the compiler detects a possible conflict between the Ada and
3984 foreign language calling sequences. For example, the use of
3985 default parameters in a convention C procedure is dubious
3986 because the C compiler cannot supply the proper default, so
3987 a warning is issued. The default is that such warnings are
3991 .. index:: -gnatwX (gcc)
3994 *Suppress warnings on Export/Import pragmas.*
3996 This switch suppresses warnings on Export/Import pragmas.
3997 The sense of this is that you are telling the compiler that
3998 you know what you are doing in writing the pragma, and it
3999 should not complain at you.
4002 .. index:: -gnatwm (gcc)
4005 *Activate warnings for No_Exception_Propagation mode.*
4007 This switch activates warnings for exception usage when pragma Restrictions
4008 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
4009 explicit exception raises which are not covered by a local handler, and for
4010 exception handlers which do not cover a local raise. The default is that
4011 these warnings are given for units that contain exception handlers.
4015 *Disable warnings for No_Exception_Propagation mode.*
4017 This switch disables warnings for exception usage when pragma Restrictions
4018 (No_Exception_Propagation) is in effect.
4021 .. index:: -gnatwy (gcc)
4022 .. index:: Ada compatibility issues warnings
4025 *Activate warnings for Ada compatibility issues.*
4027 For the most part, newer versions of Ada are upwards compatible
4028 with older versions. For example, Ada 2005 programs will almost
4029 always work when compiled as Ada 2012.
4030 However there are some exceptions (for example the fact that
4031 ``some`` is now a reserved word in Ada 2012). This
4032 switch activates several warnings to help in identifying
4033 and correcting such incompatibilities. The default is that
4034 these warnings are generated. Note that at one point Ada 2005
4035 was called Ada 0Y, hence the choice of character.
4038 .. index:: -gnatwY (gcc)
4039 .. index:: Ada compatibility issues warnings
4042 *Disable warnings for Ada compatibility issues.*
4044 This switch suppresses the warnings intended to help in identifying
4045 incompatibilities between Ada language versions.
4048 .. index:: -gnatw.y (gcc)
4049 .. index:: Package spec needing body
4052 *Activate information messages for why package spec needs body.*
4054 There are a number of cases in which a package spec needs a body.
4055 For example, the use of pragma Elaborate_Body, or the declaration
4056 of a procedure specification requiring a completion. This switch
4057 causes information messages to be output showing why a package
4058 specification requires a body. This can be useful in the case of
4059 a large package specification which is unexpectedly requiring a
4060 body. The default is that such information messages are not output.
4063 .. index:: -gnatw.Y (gcc)
4064 .. index:: No information messages for why package spec needs body
4067 *Disable information messages for why package spec needs body.*
4069 This switch suppresses the output of information messages showing why
4070 a package specification needs a body.
4073 .. index:: -gnatwz (gcc)
4074 .. index:: Unchecked_Conversion warnings
4077 *Activate warnings on unchecked conversions.*
4079 This switch activates warnings for unchecked conversions
4080 where the types are known at compile time to have different
4081 sizes. The default is that such warnings are generated. Warnings are also
4082 generated for subprogram pointers with different conventions.
4085 .. index:: -gnatwZ (gcc)
4088 *Suppress warnings on unchecked conversions.*
4090 This switch suppresses warnings for unchecked conversions
4091 where the types are known at compile time to have different
4092 sizes or conventions.
4095 .. index:: -gnatw.z (gcc)
4096 .. index:: Size/Alignment warnings
4099 *Activate warnings for size not a multiple of alignment.*
4101 This switch activates warnings for cases of array and record types
4102 with specified ``Size`` and ``Alignment`` attributes where the
4103 size is not a multiple of the alignment, resulting in an object
4104 size that is greater than the specified size. The default
4105 is that such warnings are generated.
4108 .. index:: -gnatw.Z (gcc)
4109 .. index:: Size/Alignment warnings
4112 *Suppress warnings for size not a multiple of alignment.*
4114 This switch suppresses warnings for cases of array and record types
4115 with specified ``Size`` and ``Alignment`` attributes where the
4116 size is not a multiple of the alignment, resulting in an object
4117 size that is greater than the specified size. The warning can also
4118 be suppressed by giving an explicit ``Object_Size`` value.
4121 .. index:: -Wunused (gcc)
4124 The warnings controlled by the :switch:`-gnatw` switch are generated by
4125 the front end of the compiler. The GCC back end can provide
4126 additional warnings and they are controlled by the :switch:`-W` switch.
4127 For example, :switch:`-Wunused` activates back end
4128 warnings for entities that are declared but not referenced.
4131 .. index:: -Wuninitialized (gcc)
4133 :switch:`-Wuninitialized`
4134 Similarly, :switch:`-Wuninitialized` activates
4135 the back end warning for uninitialized variables. This switch must be
4136 used in conjunction with an optimization level greater than zero.
4139 .. index:: -Wstack-usage (gcc)
4141 :switch:`-Wstack-usage={len}`
4142 Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
4143 See :ref:`Static_Stack_Usage_Analysis` for details.
4146 .. index:: -Wall (gcc)
4149 This switch enables most warnings from the GCC back end.
4150 The code generator detects a number of warning situations that are missed
4151 by the GNAT front end, and this switch can be used to activate them.
4152 The use of this switch also sets the default front end warning mode to
4153 :switch:`-gnatwa`, that is, most front end warnings activated as well.
4159 Conversely, this switch suppresses warnings from the GCC back end.
4160 The use of this switch also sets the default front end warning mode to
4161 :switch:`-gnatws`, that is, front end warnings suppressed as well.
4164 .. index:: -Werror (gcc)
4167 This switch causes warnings from the GCC back end to be treated as
4168 errors. The warning string still appears, but the warning messages are
4169 counted as errors, and prevent the generation of an object file.
4172 A string of warning parameters can be used in the same parameter. For example::
4177 will turn on all optional warnings except for unrecognized pragma warnings,
4178 and also specify that warnings should be treated as errors.
4180 When no switch :switch:`-gnatw` is used, this is equivalent to:
4182 * :switch:`-gnatw.a`
4186 * :switch:`-gnatw.b`
4190 * :switch:`-gnatw.C`
4194 * :switch:`-gnatw.D`
4198 * :switch:`-gnatw.F`
4204 * :switch:`-gnatw.H`
4210 * :switch:`-gnatw.J`
4214 * :switch:`-gnatw.K`
4218 * :switch:`-gnatw.L`
4222 * :switch:`-gnatw.m`
4226 * :switch:`-gnatw.N`
4230 * :switch:`-gnatw.O`
4234 * :switch:`-gnatw.P`
4238 * :switch:`-gnatw.Q`
4242 * :switch:`-gnatw.R`
4244 * :switch:`-gnatw.S`
4248 * :switch:`-gnatw.t`
4252 * :switch:`-gnatw.U`
4256 * :switch:`-gnatw.v`
4260 * :switch:`-gnatw.W`
4264 * :switch:`-gnatw.X`
4268 * :switch:`-gnatw.Y`
4272 * :switch:`-gnatw.z`
4274 .. _Debugging_and_Assertion_Control:
4276 Debugging and Assertion Control
4277 -------------------------------
4281 .. index:: -gnata (gcc)
4286 .. index:: Assertions
4287 .. index:: Precondition
4288 .. index:: Postcondition
4289 .. index:: Type invariants
4290 .. index:: Subtype predicates
4292 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
4294 pragma Assertion_Policy (Check);
4296 Which is a shorthand for::
4298 pragma Assertion_Policy
4300 Static_Predicate => Check,
4301 Dynamic_Predicate => Check,
4305 Post'Class => Check,
4306 Type_Invariant => Check,
4307 Type_Invariant'Class => Check);
4309 The pragmas ``Assert`` and ``Debug`` normally have no effect and
4310 are ignored. This switch, where ``a`` stands for 'assert', causes
4311 pragmas ``Assert`` and ``Debug`` to be activated. This switch also
4312 causes preconditions, postconditions, subtype predicates, and
4313 type invariants to be activated.
4315 The pragmas have the form::
4317 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4318 pragma Debug (<procedure call>)
4319 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4320 pragma Predicate (<type-local-name>, <Boolean-expression>)
4321 pragma Precondition (<Boolean-expression>, <string-expression>)
4322 pragma Postcondition (<Boolean-expression>, <string-expression>)
4324 The aspects have the form::
4326 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4327 => <Boolean-expression>;
4329 The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
4330 If the result is ``True``, the pragma has no effect (other than
4331 possible side effects from evaluating the expression). If the result is
4332 ``False``, the exception ``Assert_Failure`` declared in the package
4333 ``System.Assertions`` is raised (passing ``static-string-expression``, if
4334 present, as the message associated with the exception). If no string
4335 expression is given, the default is a string containing the file name and
4336 line number of the pragma.
4338 The ``Debug`` pragma causes ``procedure`` to be called. Note that
4339 ``pragma Debug`` may appear within a declaration sequence, allowing
4340 debugging procedures to be called between declarations.
4342 For the aspect specification, the ``Boolean-expression`` is evaluated.
4343 If the result is ``True``, the aspect has no effect. If the result
4344 is ``False``, the exception ``Assert_Failure`` is raised.
4346 .. _Validity_Checking:
4351 .. index:: Validity Checking
4353 The Ada Reference Manual defines the concept of invalid values (see
4354 RM 13.9.1). The primary source of invalid values is uninitialized
4355 variables. A scalar variable that is left uninitialized may contain
4356 an invalid value; the concept of invalid does not apply to access or
4359 It is an error to read an invalid value, but the RM does not require
4360 run-time checks to detect such errors, except for some minimal
4361 checking to prevent erroneous execution (i.e. unpredictable
4362 behavior). This corresponds to the :switch:`-gnatVd` switch below,
4363 which is the default. For example, by default, if the expression of a
4364 case statement is invalid, it will raise Constraint_Error rather than
4365 causing a wild jump, and if an array index on the left-hand side of an
4366 assignment is invalid, it will raise Constraint_Error rather than
4367 overwriting an arbitrary memory location.
4369 The :switch:`-gnatVa` may be used to enable additional validity checks,
4370 which are not required by the RM. These checks are often very
4371 expensive (which is why the RM does not require them). These checks
4372 are useful in tracking down uninitialized variables, but they are
4373 not usually recommended for production builds, and in particular
4374 we do not recommend using these extra validity checking options in
4375 combination with optimization, since this can confuse the optimizer.
4376 If performance is a consideration, leading to the need to optimize,
4377 then the validity checking options should not be used.
4379 The other :switch:`-gnatV{x}` switches below allow finer-grained
4380 control; you can enable whichever validity checks you desire. However,
4381 for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
4382 default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
4383 sufficient for non-debugging use.
4385 The :switch:`-gnatB` switch tells the compiler to assume that all
4386 values are valid (that is, within their declared subtype range)
4387 except in the context of a use of the Valid attribute. This means
4388 the compiler can generate more efficient code, since the range
4389 of values is better known at compile time. However, an uninitialized
4390 variable can cause wild jumps and memory corruption in this mode.
4392 The :switch:`-gnatV{x}` switch allows control over the validity
4393 checking mode as described below.
4394 The ``x`` argument is a string of letters that
4395 indicate validity checks that are performed or not performed in addition
4396 to the default checks required by Ada as described above.
4399 .. index:: -gnatVa (gcc)
4402 *All validity checks.*
4404 All validity checks are turned on.
4405 That is, :switch:`-gnatVa` is
4406 equivalent to ``gnatVcdfimorst``.
4409 .. index:: -gnatVc (gcc)
4412 *Validity checks for copies.*
4414 The right hand side of assignments, and the initializing values of
4415 object declarations are validity checked.
4418 .. index:: -gnatVd (gcc)
4421 *Default (RM) validity checks.*
4423 Some validity checks are done by default following normal Ada semantics
4425 A check is done in case statements that the expression is within the range
4426 of the subtype. If it is not, Constraint_Error is raised.
4427 For assignments to array components, a check is done that the expression used
4428 as index is within the range. If it is not, Constraint_Error is raised.
4429 Both these validity checks may be turned off using switch :switch:`-gnatVD`.
4430 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
4431 switch :switch:`-gnatVd` will leave the checks turned on.
4432 Switch :switch:`-gnatVD` should be used only if you are sure that all such
4433 expressions have valid values. If you use this switch and invalid values
4434 are present, then the program is erroneous, and wild jumps or memory
4435 overwriting may occur.
4438 .. index:: -gnatVe (gcc)
4441 *Validity checks for elementary components.*
4443 In the absence of this switch, assignments to record or array components are
4444 not validity checked, even if validity checks for assignments generally
4445 (:switch:`-gnatVc`) are turned on. In Ada, assignment of composite values do not
4446 require valid data, but assignment of individual components does. So for
4447 example, there is a difference between copying the elements of an array with a
4448 slice assignment, compared to assigning element by element in a loop. This
4449 switch allows you to turn off validity checking for components, even when they
4450 are assigned component by component.
4453 .. index:: -gnatVf (gcc)
4456 *Validity checks for floating-point values.*
4458 In the absence of this switch, validity checking occurs only for discrete
4459 values. If :switch:`-gnatVf` is specified, then validity checking also applies
4460 for floating-point values, and NaNs and infinities are considered invalid,
4461 as well as out of range values for constrained types. Note that this means
4462 that standard IEEE infinity mode is not allowed. The exact contexts
4463 in which floating-point values are checked depends on the setting of other
4464 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
4465 (the order does not matter) specifies that floating-point parameters of mode
4466 ``in`` should be validity checked.
4469 .. index:: -gnatVi (gcc)
4472 *Validity checks for ``in`` mode parameters.*
4474 Arguments for parameters of mode ``in`` are validity checked in function
4475 and procedure calls at the point of call.
4478 .. index:: -gnatVm (gcc)
4481 *Validity checks for ``in out`` mode parameters.*
4483 Arguments for parameters of mode ``in out`` are validity checked in
4484 procedure calls at the point of call. The ``'m'`` here stands for
4485 modify, since this concerns parameters that can be modified by the call.
4486 Note that there is no specific option to test ``out`` parameters,
4487 but any reference within the subprogram will be tested in the usual
4488 manner, and if an invalid value is copied back, any reference to it
4489 will be subject to validity checking.
4492 .. index:: -gnatVn (gcc)
4495 *No validity checks.*
4497 This switch turns off all validity checking, including the default checking
4498 for case statements and left hand side subscripts. Note that the use of
4499 the switch :switch:`-gnatp` suppresses all run-time checks, including
4500 validity checks, and thus implies :switch:`-gnatVn`. When this switch
4501 is used, it cancels any other :switch:`-gnatV` previously issued.
4504 .. index:: -gnatVo (gcc)
4507 *Validity checks for operator and attribute operands.*
4509 Arguments for predefined operators and attributes are validity checked.
4510 This includes all operators in package ``Standard``,
4511 the shift operators defined as intrinsic in package ``Interfaces``
4512 and operands for attributes such as ``Pos``. Checks are also made
4513 on individual component values for composite comparisons, and on the
4514 expressions in type conversions and qualified expressions. Checks are
4515 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4518 .. index:: -gnatVp (gcc)
4521 *Validity checks for parameters.*
4523 This controls the treatment of parameters within a subprogram (as opposed
4524 to :switch:`-gnatVi` and :switch:`-gnatVm` which control validity testing
4525 of parameters on a call. If either of these call options is used, then
4526 normally an assumption is made within a subprogram that the input arguments
4527 have been validity checking at the point of call, and do not need checking
4528 again within a subprogram). If :switch:`-gnatVp` is set, then this assumption
4529 is not made, and parameters are not assumed to be valid, so their validity
4530 will be checked (or rechecked) within the subprogram.
4533 .. index:: -gnatVr (gcc)
4536 *Validity checks for function returns.*
4538 The expression in ``return`` statements in functions is validity
4542 .. index:: -gnatVs (gcc)
4545 *Validity checks for subscripts.*
4547 All subscripts expressions are checked for validity, whether they appear
4548 on the right side or left side (in default mode only left side subscripts
4549 are validity checked).
4552 .. index:: -gnatVt (gcc)
4555 *Validity checks for tests.*
4557 Expressions used as conditions in ``if``, ``while`` or ``exit``
4558 statements are checked, as well as guard expressions in entry calls.
4561 The :switch:`-gnatV` switch may be followed by a string of letters
4562 to turn on a series of validity checking options.
4563 For example, :switch:`-gnatVcr`
4564 specifies that in addition to the default validity checking, copies and
4565 function return expressions are to be validity checked.
4566 In order to make it easier to specify the desired combination of effects,
4567 the upper case letters ``CDFIMORST`` may
4568 be used to turn off the corresponding lower case option.
4569 Thus :switch:`-gnatVaM` turns on all validity checking options except for
4570 checking of ``in out`` parameters.
4572 The specification of additional validity checking generates extra code (and
4573 in the case of :switch:`-gnatVa` the code expansion can be substantial).
4574 However, these additional checks can be very useful in detecting
4575 uninitialized variables, incorrect use of unchecked conversion, and other
4576 errors leading to invalid values. The use of pragma ``Initialize_Scalars``
4577 is useful in conjunction with the extra validity checking, since this
4578 ensures that wherever possible uninitialized variables have invalid values.
4580 See also the pragma ``Validity_Checks`` which allows modification of
4581 the validity checking mode at the program source level, and also allows for
4582 temporary disabling of validity checks.
4589 .. index:: Style checking
4591 .. index:: -gnaty (gcc)
4593 The :switch:`-gnatyx` switch causes the compiler to
4594 enforce specified style rules. A limited set of style rules has been used
4595 in writing the GNAT sources themselves. This switch allows user programs
4596 to activate all or some of these checks. If the source program fails a
4597 specified style check, an appropriate message is given, preceded by
4598 the character sequence '(style)'. This message does not prevent
4599 successful compilation (unless the :switch:`-gnatwe` switch is used).
4601 Note that this is by no means intended to be a general facility for
4602 checking arbitrary coding standards. It is simply an embedding of the
4603 style rules we have chosen for the GNAT sources. If you are starting
4604 a project which does not have established style standards, you may
4605 find it useful to adopt the entire set of GNAT coding standards, or
4606 some subset of them.
4608 .. only:: PRO or GPL
4610 If you already have an established set of coding
4611 standards, then the selected style checking options may
4612 indeed correspond to choices you have made, but for general checking
4613 of an existing set of coding rules, you should look to the gnatcheck
4614 tool, which is designed for that purpose.
4616 The string ``x`` is a sequence of letters or digits
4617 indicating the particular style
4618 checks to be performed. The following checks are defined:
4621 .. index:: -gnaty[0-9] (gcc)
4624 *Specify indentation level.*
4626 If a digit from 1-9 appears
4627 in the string after :switch:`-gnaty`
4628 then proper indentation is checked, with the digit indicating the
4629 indentation level required. A value of zero turns off this style check.
4630 The general style of required indentation is as specified by
4631 the examples in the Ada Reference Manual. Full line comments must be
4632 aligned with the ``--`` starting on a column that is a multiple of
4633 the alignment level, or they may be aligned the same way as the following
4634 non-blank line (this is useful when full line comments appear in the middle
4635 of a statement, or they may be aligned with the source line on the previous
4638 .. index:: -gnatya (gcc)
4641 *Check attribute casing.*
4643 Attribute names, including the case of keywords such as ``digits``
4644 used as attributes names, must be written in mixed case, that is, the
4645 initial letter and any letter following an underscore must be uppercase.
4646 All other letters must be lowercase.
4649 .. index:: -gnatyA (gcc)
4652 *Use of array index numbers in array attributes.*
4654 When using the array attributes First, Last, Range,
4655 or Length, the index number must be omitted for one-dimensional arrays
4656 and is required for multi-dimensional arrays.
4659 .. index:: -gnatyb (gcc)
4662 *Blanks not allowed at statement end.*
4664 Trailing blanks are not allowed at the end of statements. The purpose of this
4665 rule, together with h (no horizontal tabs), is to enforce a canonical format
4666 for the use of blanks to separate source tokens.
4669 .. index:: -gnatyB (gcc)
4672 *Check Boolean operators.*
4674 The use of AND/OR operators is not permitted except in the cases of modular
4675 operands, array operands, and simple stand-alone boolean variables or
4676 boolean constants. In all other cases ``and then``/`or else` are
4680 .. index:: -gnatyc (gcc)
4683 *Check comments, double space.*
4685 Comments must meet the following set of rules:
4687 * The ``--`` that starts the column must either start in column one,
4688 or else at least one blank must precede this sequence.
4690 * Comments that follow other tokens on a line must have at least one blank
4691 following the ``--`` at the start of the comment.
4693 * Full line comments must have at least two blanks following the
4694 ``--`` that starts the comment, with the following exceptions.
4696 * A line consisting only of the ``--`` characters, possibly preceded
4697 by blanks is permitted.
4699 * A comment starting with ``--x`` where ``x`` is a special character
4701 This allows proper processing of the output from specialized tools
4702 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
4704 language (where ``--#`` is used). For the purposes of this rule, a
4705 special character is defined as being in one of the ASCII ranges
4706 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
4707 Note that this usage is not permitted
4708 in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
4710 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4711 permitted. This allows the construction of box comments where lines of minus
4712 signs are used to form the top and bottom of the box.
4714 * A comment that starts and ends with ``--`` is permitted as long as at
4715 least one blank follows the initial ``--``. Together with the preceding
4716 rule, this allows the construction of box comments, as shown in the following
4721 ---------------------------
4722 -- This is a box comment --
4723 -- with two text lines. --
4724 ---------------------------
4727 .. index:: -gnatyC (gcc)
4730 *Check comments, single space.*
4732 This is identical to ``c`` except that only one space
4733 is required following the ``--`` of a comment instead of two.
4736 .. index:: -gnatyd (gcc)
4739 *Check no DOS line terminators present.*
4741 All lines must be terminated by a single ASCII.LF
4742 character (in particular the DOS line terminator sequence CR/LF is not
4746 .. index:: -gnatyD (gcc)
4749 *Check declared identifiers in mixed case.*
4751 Declared identifiers must be in mixed case, as in
4752 This_Is_An_Identifier. Use -gnatyr in addition to ensure
4753 that references match declarations.
4756 .. index:: -gnatye (gcc)
4759 *Check end/exit labels.*
4761 Optional labels on ``end`` statements ending subprograms and on
4762 ``exit`` statements exiting named loops, are required to be present.
4765 .. index:: -gnatyf (gcc)
4768 *No form feeds or vertical tabs.*
4770 Neither form feeds nor vertical tab characters are permitted
4774 .. index:: -gnatyg (gcc)
4779 The set of style check switches is set to match that used by the GNAT sources.
4780 This may be useful when developing code that is eventually intended to be
4781 incorporated into GNAT. Currently this is equivalent to :switch:`-gnatyydISux`)
4782 but additional style switches may be added to this set in the future without
4786 .. index:: -gnatyh (gcc)
4789 *No horizontal tabs.*
4791 Horizontal tab characters are not permitted in the source text.
4792 Together with the b (no blanks at end of line) check, this
4793 enforces a canonical form for the use of blanks to separate
4797 .. index:: -gnatyi (gcc)
4800 *Check if-then layout.*
4802 The keyword ``then`` must appear either on the same
4803 line as corresponding ``if``, or on a line on its own, lined
4804 up under the ``if``.
4807 .. index:: -gnatyI (gcc)
4810 *check mode IN keywords.*
4812 Mode ``in`` (the default mode) is not
4813 allowed to be given explicitly. ``in out`` is fine,
4814 but not ``in`` on its own.
4817 .. index:: -gnatyk (gcc)
4820 *Check keyword casing.*
4822 All keywords must be in lower case (with the exception of keywords
4823 such as ``digits`` used as attribute names to which this check
4827 .. index:: -gnatyl (gcc)
4832 Layout of statement and declaration constructs must follow the
4833 recommendations in the Ada Reference Manual, as indicated by the
4834 form of the syntax rules. For example an ``else`` keyword must
4835 be lined up with the corresponding ``if`` keyword.
4837 There are two respects in which the style rule enforced by this check
4838 option are more liberal than those in the Ada Reference Manual. First
4839 in the case of record declarations, it is permissible to put the
4840 ``record`` keyword on the same line as the ``type`` keyword, and
4841 then the ``end`` in ``end record`` must line up under ``type``.
4842 This is also permitted when the type declaration is split on two lines.
4843 For example, any of the following three layouts is acceptable:
4864 Second, in the case of a block statement, a permitted alternative
4865 is to put the block label on the same line as the ``declare`` or
4866 ``begin`` keyword, and then line the ``end`` keyword up under
4867 the block label. For example both the following are permitted:
4884 The same alternative format is allowed for loops. For example, both of
4885 the following are permitted:
4889 Clear : while J < 10 loop
4899 .. index:: -gnatyLnnn (gcc)
4902 *Set maximum nesting level.*
4904 The maximum level of nesting of constructs (including subprograms, loops,
4905 blocks, packages, and conditionals) may not exceed the given value
4906 *nnn*. A value of zero disconnects this style check.
4909 .. index:: -gnatym (gcc)
4912 *Check maximum line length.*
4914 The length of source lines must not exceed 79 characters, including
4915 any trailing blanks. The value of 79 allows convenient display on an
4916 80 character wide device or window, allowing for possible special
4917 treatment of 80 character lines. Note that this count is of
4918 characters in the source text. This means that a tab character counts
4919 as one character in this count and a wide character sequence counts as
4920 a single character (however many bytes are needed in the encoding).
4923 .. index:: -gnatyMnnn (gcc)
4926 *Set maximum line length.*
4928 The length of lines must not exceed the
4929 given value *nnn*. The maximum value that can be specified is 32767.
4930 If neither style option for setting the line length is used, then the
4931 default is 255. This also controls the maximum length of lexical elements,
4932 where the only restriction is that they must fit on a single line.
4935 .. index:: -gnatyn (gcc)
4938 *Check casing of entities in Standard.*
4940 Any identifier from Standard must be cased
4941 to match the presentation in the Ada Reference Manual (for example,
4942 ``Integer`` and ``ASCII.NUL``).
4945 .. index:: -gnatyN (gcc)
4948 *Turn off all style checks.*
4950 All style check options are turned off.
4953 .. index:: -gnatyo (gcc)
4956 *Check order of subprogram bodies.*
4958 All subprogram bodies in a given scope
4959 (e.g., a package body) must be in alphabetical order. The ordering
4960 rule uses normal Ada rules for comparing strings, ignoring casing
4961 of letters, except that if there is a trailing numeric suffix, then
4962 the value of this suffix is used in the ordering (e.g., Junk2 comes
4966 .. index:: -gnatyO (gcc)
4969 *Check that overriding subprograms are explicitly marked as such.*
4971 This applies to all subprograms of a derived type that override a primitive
4972 operation of the type, for both tagged and untagged types. In particular,
4973 the declaration of a primitive operation of a type extension that overrides
4974 an inherited operation must carry an overriding indicator. Another case is
4975 the declaration of a function that overrides a predefined operator (such
4976 as an equality operator).
4979 .. index:: -gnatyp (gcc)
4982 *Check pragma casing.*
4984 Pragma names must be written in mixed case, that is, the
4985 initial letter and any letter following an underscore must be uppercase.
4986 All other letters must be lowercase. An exception is that SPARK_Mode is
4987 allowed as an alternative for Spark_Mode.
4990 .. index:: -gnatyr (gcc)
4995 All identifier references must be cased in the same way as the
4996 corresponding declaration. No specific casing style is imposed on
4997 identifiers. The only requirement is for consistency of references
5001 .. index:: -gnatys (gcc)
5004 *Check separate specs.*
5006 Separate declarations ('specs') are required for subprograms (a
5007 body is not allowed to serve as its own declaration). The only
5008 exception is that parameterless library level procedures are
5009 not required to have a separate declaration. This exception covers
5010 the most frequent form of main program procedures.
5013 .. index:: -gnatyS (gcc)
5016 *Check no statements after then/else.*
5018 No statements are allowed
5019 on the same line as a ``then`` or ``else`` keyword following the
5020 keyword in an ``if`` statement. ``or else`` and ``and then`` are not
5021 affected, and a special exception allows a pragma to appear after ``else``.
5024 .. index:: -gnatyt (gcc)
5027 *Check token spacing.*
5029 The following token spacing rules are enforced:
5031 * The keywords ``abs`` and ``not`` must be followed by a space.
5033 * The token ``=>`` must be surrounded by spaces.
5035 * The token ``<>`` must be preceded by a space or a left parenthesis.
5037 * Binary operators other than ``**`` must be surrounded by spaces.
5038 There is no restriction on the layout of the ``**`` binary operator.
5040 * Colon must be surrounded by spaces.
5042 * Colon-equal (assignment, initialization) must be surrounded by spaces.
5044 * Comma must be the first non-blank character on the line, or be
5045 immediately preceded by a non-blank character, and must be followed
5048 * If the token preceding a left parenthesis ends with a letter or digit, then
5049 a space must separate the two tokens.
5051 * If the token following a right parenthesis starts with a letter or digit, then
5052 a space must separate the two tokens.
5054 * A right parenthesis must either be the first non-blank character on
5055 a line, or it must be preceded by a non-blank character.
5057 * A semicolon must not be preceded by a space, and must not be followed by
5058 a non-blank character.
5060 * A unary plus or minus may not be followed by a space.
5062 * A vertical bar must be surrounded by spaces.
5064 Exactly one blank (and no other white space) must appear between
5065 a ``not`` token and a following ``in`` token.
5068 .. index:: -gnatyu (gcc)
5071 *Check unnecessary blank lines.*
5073 Unnecessary blank lines are not allowed. A blank line is considered
5074 unnecessary if it appears at the end of the file, or if more than
5075 one blank line occurs in sequence.
5078 .. index:: -gnatyx (gcc)
5081 *Check extra parentheses.*
5083 Unnecessary extra level of parentheses (C-style) are not allowed
5084 around conditions in ``if`` statements, ``while`` statements and
5085 ``exit`` statements.
5088 .. index:: -gnatyy (gcc)
5091 *Set all standard style check options.*
5093 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
5094 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
5095 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
5096 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
5099 .. index:: -gnaty- (gcc)
5102 *Remove style check options.*
5104 This causes any subsequent options in the string to act as canceling the
5105 corresponding style check option. To cancel maximum nesting level control,
5106 use the ``L`` parameter without any integer value after that, because any
5107 digit following *-* in the parameter string of the :switch:`-gnaty`
5108 option will be treated as canceling the indentation check. The same is true
5109 for the ``M`` parameter. ``y`` and ``N`` parameters are not
5113 .. index:: -gnaty+ (gcc)
5116 *Enable style check options.*
5118 This causes any subsequent options in the string to enable the corresponding
5119 style check option. That is, it cancels the effect of a previous -,
5123 .. end of switch description (leave this comment to ease automatic parsing for
5126 In the above rules, appearing in column one is always permitted, that is,
5127 counts as meeting either a requirement for a required preceding space,
5128 or as meeting a requirement for no preceding space.
5130 Appearing at the end of a line is also always permitted, that is, counts
5131 as meeting either a requirement for a following space, or as meeting
5132 a requirement for no following space.
5134 If any of these style rules is violated, a message is generated giving
5135 details on the violation. The initial characters of such messages are
5136 always '`(style)`'. Note that these messages are treated as warning
5137 messages, so they normally do not prevent the generation of an object
5138 file. The :switch:`-gnatwe` switch can be used to treat warning messages,
5139 including style messages, as fatal errors.
5141 The switch :switch:`-gnaty` on its own (that is not
5142 followed by any letters or digits) is equivalent
5143 to the use of :switch:`-gnatyy` as described above, that is all
5144 built-in standard style check options are enabled.
5146 The switch :switch:`-gnatyN` clears any previously set style checks.
5148 .. _Run-Time_Checks:
5153 .. index:: Division by zero
5155 .. index:: Access before elaboration
5157 .. index:: Checks, division by zero
5159 .. index:: Checks, access before elaboration
5161 .. index:: Checks, stack overflow checking
5163 By default, the following checks are suppressed: stack overflow
5164 checks, and checks for access before elaboration on subprogram
5165 calls. All other checks, including overflow checks, range checks and
5166 array bounds checks, are turned on by default. The following ``gcc``
5167 switches refine this default behavior.
5169 .. index:: -gnatp (gcc)
5172 .. index:: Suppressing checks
5174 .. index:: Checks, suppressing
5176 This switch causes the unit to be compiled
5177 as though ``pragma Suppress (All_checks)``
5178 had been present in the source. Validity checks are also eliminated (in
5179 other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
5180 Use this switch to improve the performance
5181 of the code at the expense of safety in the presence of invalid data or
5184 Note that when checks are suppressed, the compiler is allowed, but not
5185 required, to omit the checking code. If the run-time cost of the
5186 checking code is zero or near-zero, the compiler will generate it even
5187 if checks are suppressed. In particular, if the compiler can prove
5188 that a certain check will necessarily fail, it will generate code to
5189 do an unconditional 'raise', even if checks are suppressed. The
5190 compiler warns in this case. Another case in which checks may not be
5191 eliminated is when they are embedded in certain run-time routines such
5192 as math library routines.
5194 Of course, run-time checks are omitted whenever the compiler can prove
5195 that they will not fail, whether or not checks are suppressed.
5197 Note that if you suppress a check that would have failed, program
5198 execution is erroneous, which means the behavior is totally
5199 unpredictable. The program might crash, or print wrong answers, or
5200 do anything else. It might even do exactly what you wanted it to do
5201 (and then it might start failing mysteriously next week or next
5202 year). The compiler will generate code based on the assumption that
5203 the condition being checked is true, which can result in erroneous
5204 execution if that assumption is wrong.
5206 The checks subject to suppression include all the checks defined by the Ada
5207 standard, the additional implementation defined checks ``Alignment_Check``,
5208 ``Duplicated_Tag_Check``, ``Predicate_Check``, ``Container_Checks``, ``Tampering_Check``,
5209 and ``Validity_Check``, as well as any checks introduced using ``pragma Check_Name``.
5210 Note that ``Atomic_Synchronization`` is not automatically suppressed by use of this option.
5212 If the code depends on certain checks being active, you can use
5213 pragma ``Unsuppress`` either as a configuration pragma or as
5214 a local pragma to make sure that a specified check is performed
5215 even if ``gnatp`` is specified.
5217 The :switch:`-gnatp` switch has no effect if a subsequent
5218 :switch:`-gnat-p` switch appears.
5221 .. index:: -gnat-p (gcc)
5222 .. index:: Suppressing checks
5223 .. index:: Checks, suppressing
5227 This switch cancels the effect of a previous ``gnatp`` switch.
5230 .. index:: -gnato?? (gcc)
5231 .. index:: Overflow checks
5232 .. index:: Overflow mode
5233 .. index:: Check, overflow
5236 This switch controls the mode used for computing intermediate
5237 arithmetic integer operations, and also enables overflow checking.
5238 For a full description of overflow mode and checking control, see
5239 the 'Overflow Check Handling in GNAT' appendix in this
5242 Overflow checks are always enabled by this switch. The argument
5243 controls the mode, using the codes
5247 In STRICT mode, intermediate operations are always done using the
5248 base type, and overflow checking ensures that the result is within
5249 the base type range.
5253 In MINIMIZED mode, overflows in intermediate operations are avoided
5254 where possible by using a larger integer type for the computation
5255 (typically ``Long_Long_Integer``). Overflow checking ensures that
5256 the result fits in this larger integer type.
5260 In ELIMINATED mode, overflows in intermediate operations are avoided
5261 by using multi-precision arithmetic. In this case, overflow checking
5262 has no effect on intermediate operations (since overflow is impossible).
5264 If two digits are present after :switch:`-gnato` then the first digit
5265 sets the mode for expressions outside assertions, and the second digit
5266 sets the mode for expressions within assertions. Here assertions is used
5267 in the technical sense (which includes for example precondition and
5268 postcondition expressions).
5270 If one digit is present, the corresponding mode is applicable to both
5271 expressions within and outside assertion expressions.
5273 If no digits are present, the default is to enable overflow checks
5274 and set STRICT mode for both kinds of expressions. This is compatible
5275 with the use of :switch:`-gnato` in previous versions of GNAT.
5277 .. index:: Machine_Overflows
5279 Note that the :switch:`-gnato??` switch does not affect the code generated
5280 for any floating-point operations; it applies only to integer semantics.
5281 For floating-point, GNAT has the ``Machine_Overflows``
5282 attribute set to ``False`` and the normal mode of operation is to
5283 generate IEEE NaN and infinite values on overflow or invalid operations
5284 (such as dividing 0.0 by 0.0).
5286 The reason that we distinguish overflow checking from other kinds of
5287 range constraint checking is that a failure of an overflow check, unlike
5288 for example the failure of a range check, can result in an incorrect
5289 value, but cannot cause random memory destruction (like an out of range
5290 subscript), or a wild jump (from an out of range case value). Overflow
5291 checking is also quite expensive in time and space, since in general it
5292 requires the use of double length arithmetic.
5294 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
5295 so overflow checking is performed in STRICT mode by default.
5298 .. index:: -gnatE (gcc)
5299 .. index:: Elaboration checks
5300 .. index:: Check, elaboration
5303 Enables dynamic checks for access-before-elaboration
5304 on subprogram calls and generic instantiations.
5305 Note that :switch:`-gnatE` is not necessary for safety, because in the
5306 default mode, GNAT ensures statically that the checks would not fail.
5307 For full details of the effect and use of this switch,
5308 :ref:`Compiling_with_gcc`.
5311 .. index:: -fstack-check (gcc)
5312 .. index:: Stack Overflow Checking
5313 .. index:: Checks, stack overflow checking
5315 :switch:`-fstack-check`
5316 Activates stack overflow checking. For full details of the effect and use of
5317 this switch see :ref:`Stack_Overflow_Checking`.
5319 .. index:: Unsuppress
5321 The setting of these switches only controls the default setting of the
5322 checks. You may modify them using either ``Suppress`` (to remove
5323 checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
5327 .. _Using_gcc_for_Syntax_Checking:
5329 Using ``gcc`` for Syntax Checking
5330 ---------------------------------
5332 .. index:: -gnats (gcc)
5335 The ``s`` stands for 'syntax'.
5337 Run GNAT in syntax checking only mode. For
5338 example, the command
5342 $ gcc -c -gnats x.adb
5344 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5345 series of files in a single command
5346 , and can use wildcards to specify such a group of files.
5347 Note that you must specify the :switch:`-c` (compile
5348 only) flag in addition to the :switch:`-gnats` flag.
5350 You may use other switches in conjunction with :switch:`-gnats`. In
5351 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
5352 format of any generated error messages.
5354 When the source file is empty or contains only empty lines and/or comments,
5355 the output is a warning:
5360 $ gcc -c -gnats -x ada toto.txt
5361 toto.txt:1:01: warning: empty file, contains no compilation units
5365 Otherwise, the output is simply the error messages, if any. No object file or
5366 ALI file is generated by a syntax-only compilation. Also, no units other
5367 than the one specified are accessed. For example, if a unit ``X``
5368 |withs| a unit ``Y``, compiling unit ``X`` in syntax
5369 check only mode does not access the source file containing unit
5372 .. index:: Multiple units, syntax checking
5374 Normally, GNAT allows only a single unit in a source file. However, this
5375 restriction does not apply in syntax-check-only mode, and it is possible
5376 to check a file containing multiple compilation units concatenated
5377 together. This is primarily used by the ``gnatchop`` utility
5378 (:ref:`Renaming_Files_with_gnatchop`).
5380 .. _Using_gcc_for_Semantic_Checking:
5382 Using ``gcc`` for Semantic Checking
5383 -----------------------------------
5387 .. index:: -gnatc (gcc)
5390 The ``c`` stands for 'check'.
5391 Causes the compiler to operate in semantic check mode,
5392 with full checking for all illegalities specified in the
5393 Ada Reference Manual, but without generation of any object code
5394 (no object file is generated).
5396 Because dependent files must be accessed, you must follow the GNAT
5397 semantic restrictions on file structuring to operate in this mode:
5399 * The needed source files must be accessible
5400 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5402 * Each file must contain only one compilation unit.
5404 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5406 The output consists of error messages as appropriate. No object file is
5407 generated. An :file:`ALI` file is generated for use in the context of
5408 cross-reference tools, but this file is marked as not being suitable
5409 for binding (since no object file is generated).
5410 The checking corresponds exactly to the notion of
5411 legality in the Ada Reference Manual.
5413 Any unit can be compiled in semantics-checking-only mode, including
5414 units that would not normally be compiled (subunits,
5415 and specifications where a separate body is present).
5417 .. _Compiling_Different_Versions_of_Ada:
5419 Compiling Different Versions of Ada
5420 -----------------------------------
5422 The switches described in this section allow you to explicitly specify
5423 the version of the Ada language that your programs are written in.
5424 The default mode is Ada 2012,
5425 but you can also specify Ada 95, Ada 2005 mode, or
5426 indicate Ada 83 compatibility mode.
5429 .. index:: Compatibility with Ada 83
5430 .. index:: -gnat83 (gcc)
5431 .. index:: ACVC, Ada 83 tests
5432 .. index:: Ada 83 mode
5434 :switch:`-gnat83` (Ada 83 Compatibility Mode)
5435 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5436 specifies that the program is to be compiled in Ada 83 mode. With
5437 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5438 semantics where this can be done easily.
5439 It is not possible to guarantee this switch does a perfect
5440 job; some subtle tests, such as are
5441 found in earlier ACVC tests (and that have been removed from the ACATS suite
5442 for Ada 95), might not compile correctly.
5443 Nevertheless, this switch may be useful in some circumstances, for example
5444 where, due to contractual reasons, existing code needs to be maintained
5445 using only Ada 83 features.
5447 With few exceptions (most notably the need to use ``<>`` on
5448 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5449 the use of the new Ada 95 / Ada 2005
5450 reserved words, and the use of packages
5451 with optional bodies), it is not necessary to specify the
5452 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
5453 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5454 a correct Ada 83 program is usually also a correct program
5455 in these later versions of the language standard. For further information
5456 please refer to the *Compatibility and Porting Guide* chapter in the
5457 :title:`GNAT Reference Manual`.
5460 .. index:: -gnat95 (gcc)
5461 .. index:: Ada 95 mode
5463 :switch:`-gnat95` (Ada 95 mode)
5464 This switch directs the compiler to implement the Ada 95 version of the
5466 Since Ada 95 is almost completely upwards
5467 compatible with Ada 83, Ada 83 programs may generally be compiled using
5468 this switch (see the description of the :switch:`-gnat83` switch for further
5469 information about Ada 83 mode).
5470 If an Ada 2005 program is compiled in Ada 95 mode,
5471 uses of the new Ada 2005 features will cause error
5472 messages or warnings.
5474 This switch also can be used to cancel the effect of a previous
5475 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
5476 switch earlier in the command line.
5479 .. index:: -gnat05 (gcc)
5480 .. index:: -gnat2005 (gcc)
5481 .. index:: Ada 2005 mode
5483 :switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
5484 This switch directs the compiler to implement the Ada 2005 version of the
5485 language, as documented in the official Ada standards document.
5486 Since Ada 2005 is almost completely upwards
5487 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5488 may generally be compiled using this switch (see the description of the
5489 :switch:`-gnat83` and :switch:`-gnat95` switches for further
5493 .. index:: -gnat12 (gcc)
5494 .. index:: -gnat2012 (gcc)
5495 .. index:: Ada 2012 mode
5497 :switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
5498 This switch directs the compiler to implement the Ada 2012 version of the
5499 language (also the default).
5500 Since Ada 2012 is almost completely upwards
5501 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5502 Ada 83 and Ada 95 programs
5503 may generally be compiled using this switch (see the description of the
5504 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
5505 for further information).
5508 .. index:: -gnatX (gcc)
5509 .. index:: Ada language extensions
5510 .. index:: GNAT extensions
5512 :switch:`-gnatX` (Enable GNAT Extensions)
5513 This switch directs the compiler to implement the latest version of the
5514 language (currently Ada 2012) and also to enable certain GNAT implementation
5515 extensions that are not part of any Ada standard. For a full list of these
5516 extensions, see the GNAT reference manual.
5519 .. _Character_Set_Control:
5521 Character Set Control
5522 ---------------------
5524 .. index:: -gnati (gcc)
5527 Normally GNAT recognizes the Latin-1 character set in source program
5528 identifiers, as described in the Ada Reference Manual.
5530 GNAT to recognize alternate character sets in identifiers. ``c`` is a
5531 single character indicating the character set, as follows:
5533 ========== ======================================================
5534 *1* ISO 8859-1 (Latin-1) identifiers
5535 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5536 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5537 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5538 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5539 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5540 *p* IBM PC letters (code page 437) allowed in identifiers
5541 *8* IBM PC letters (code page 850) allowed in identifiers
5542 *f* Full upper-half codes allowed in identifiers
5543 *n* No upper-half codes allowed in identifiers
5544 *w* Wide-character codes (that is, codes greater than 255)
5545 allowed in identifiers
5546 ========== ======================================================
5548 See :ref:`Foreign_Language_Representation` for full details on the
5549 implementation of these character sets.
5552 .. index:: -gnatW (gcc)
5555 Specify the method of encoding for wide characters.
5556 ``e`` is one of the following:
5558 ========== ======================================================
5559 *h* Hex encoding (brackets coding also recognized)
5560 *u* Upper half encoding (brackets encoding also recognized)
5561 *s* Shift/JIS encoding (brackets encoding also recognized)
5562 *e* EUC encoding (brackets encoding also recognized)
5563 *8* UTF-8 encoding (brackets encoding also recognized)
5564 *b* Brackets encoding only (default value)
5565 ========== ======================================================
5567 For full details on these encoding
5568 methods see :ref:`Wide_Character_Encodings`.
5569 Note that brackets coding is always accepted, even if one of the other
5570 options is specified, so for example :switch:`-gnatW8` specifies that both
5571 brackets and UTF-8 encodings will be recognized. The units that are
5572 with'ed directly or indirectly will be scanned using the specified
5573 representation scheme, and so if one of the non-brackets scheme is
5574 used, it must be used consistently throughout the program. However,
5575 since brackets encoding is always recognized, it may be conveniently
5576 used in standard libraries, allowing these libraries to be used with
5577 any of the available coding schemes.
5579 Note that brackets encoding only applies to program text. Within comments,
5580 brackets are considered to be normal graphic characters, and bracket sequences
5581 are never recognized as wide characters.
5583 If no :switch:`-gnatW?` parameter is present, then the default
5584 representation is normally Brackets encoding only. However, if the
5585 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5586 byte order mark or BOM for UTF-8), then these three characters are
5587 skipped and the default representation for the file is set to UTF-8.
5589 Note that the wide character representation that is specified (explicitly
5590 or by default) for the main program also acts as the default encoding used
5591 for Wide_Text_IO files if not specifically overridden by a WCEM form
5595 When no :switch:`-gnatW?` is specified, then characters (other than wide
5596 characters represented using brackets notation) are treated as 8-bit
5597 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5598 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5599 characters in the range 16#00#..16#1F# are not accepted in program text
5600 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5601 in program text, but allowed and ignored in comments. Note in particular
5602 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5603 as an end of line in this default mode. If your source program contains
5604 instances of the NEL character used as a line terminator,
5605 you must use UTF-8 encoding for the whole
5606 source program. In default mode, all lines must be ended by a standard
5607 end of line sequence (CR, CR/LF, or LF).
5609 Note that the convention of simply accepting all upper half characters in
5610 comments means that programs that use standard ASCII for program text, but
5611 UTF-8 encoding for comments are accepted in default mode, providing that the
5612 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5613 This is a common mode for many programs with foreign language comments.
5615 .. _File_Naming_Control:
5620 .. index:: -gnatk (gcc)
5623 Activates file name 'krunching'. ``n``, a decimal integer in the range
5624 1-999, indicates the maximum allowable length of a file name (not
5625 including the :file:`.ads` or :file:`.adb` extension). The default is not
5626 to enable file name krunching.
5628 For the source file naming rules, :ref:`File_Naming_Rules`.
5630 .. _Subprogram_Inlining_Control:
5632 Subprogram Inlining Control
5633 ---------------------------
5635 .. index:: -gnatn (gcc)
5637 :switch:`-gnatn[12]`
5638 The ``n`` here is intended to suggest the first syllable of the word 'inline'.
5639 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
5640 actually occur, optimization must be enabled and, by default, inlining of
5641 subprograms across units is not performed. If you want to additionally
5642 enable inlining of subprograms specified by pragma ``Inline`` across units,
5643 you must also specify this switch.
5645 In the absence of this switch, GNAT does not attempt inlining across units
5646 and does not access the bodies of subprograms for which ``pragma Inline`` is
5647 specified if they are not in the current unit.
5649 You can optionally specify the inlining level: 1 for moderate inlining across
5650 units, which is a good compromise between compilation times and performances
5651 at run time, or 2 for full inlining across units, which may bring about
5652 longer compilation times. If no inlining level is specified, the compiler will
5653 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
5654 :switch:`-Os` and 2 for :switch:`-O3`.
5656 If you specify this switch the compiler will access these bodies,
5657 creating an extra source dependency for the resulting object file, and
5658 where possible, the call will be inlined.
5659 For further details on when inlining is possible
5660 see :ref:`Inlining_of_Subprograms`.
5663 .. index:: -gnatN (gcc)
5666 This switch activates front-end inlining which also
5667 generates additional dependencies.
5669 When using a gcc-based back end (in practice this means using any version
5670 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
5671 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
5672 Historically front end inlining was more extensive than the gcc back end
5673 inlining, but that is no longer the case.
5675 .. _Auxiliary_Output_Control:
5677 Auxiliary Output Control
5678 ------------------------
5680 .. index:: -gnatu (gcc)
5683 Print a list of units required by this compilation on :file:`stdout`.
5684 The listing includes all units on which the unit being compiled depends
5685 either directly or indirectly.
5688 .. index:: -pass-exit-codes (gcc)
5690 :switch:`-pass-exit-codes`
5691 If this switch is not used, the exit code returned by ``gcc`` when
5692 compiling multiple files indicates whether all source files have
5693 been successfully used to generate object files or not.
5695 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
5696 exit status and allows an integrated development environment to better
5697 react to a compilation failure. Those exit status are:
5699 ========== ======================================================
5700 *5* There was an error in at least one source file.
5701 *3* At least one source file did not generate an object file.
5702 *2* The compiler died unexpectedly (internal error for example).
5703 *0* An object file has been generated for every source file.
5704 ========== ======================================================
5706 .. _Debugging_Control:
5711 .. index:: Debugging options
5714 .. index:: -gnatd (gcc)
5717 Activate internal debugging switches. ``x`` is a letter or digit, or
5718 string of letters or digits, which specifies the type of debugging
5719 outputs desired. Normally these are used only for internal development
5720 or system debugging purposes. You can find full documentation for these
5721 switches in the body of the ``Debug`` unit in the compiler source
5722 file :file:`debug.adb`.
5725 .. index:: -gnatG (gcc)
5727 :switch:`-gnatG[={nn}]`
5728 This switch causes the compiler to generate auxiliary output containing
5729 a pseudo-source listing of the generated expanded code. Like most Ada
5730 compilers, GNAT works by first transforming the high level Ada code into
5731 lower level constructs. For example, tasking operations are transformed
5732 into calls to the tasking run-time routines. A unique capability of GNAT
5733 is to list this expanded code in a form very close to normal Ada source.
5734 This is very useful in understanding the implications of various Ada
5735 usage on the efficiency of the generated code. There are many cases in
5736 Ada (e.g., the use of controlled types), where simple Ada statements can
5737 generate a lot of run-time code. By using :switch:`-gnatG` you can identify
5738 these cases, and consider whether it may be desirable to modify the coding
5739 approach to improve efficiency.
5741 The optional parameter ``nn`` if present after -gnatG specifies an
5742 alternative maximum line length that overrides the normal default of 72.
5743 This value is in the range 40-999999, values less than 40 being silently
5744 reset to 40. The equal sign is optional.
5746 The format of the output is very similar to standard Ada source, and is
5747 easily understood by an Ada programmer. The following special syntactic
5748 additions correspond to low level features used in the generated code that
5749 do not have any exact analogies in pure Ada source form. The following
5750 is a partial list of these special constructions. See the spec
5751 of package ``Sprint`` in file :file:`sprint.ads` for a full list.
5753 .. index:: -gnatL (gcc)
5755 If the switch :switch:`-gnatL` is used in conjunction with
5756 :switch:`-gnatG`, then the original source lines are interspersed
5757 in the expanded source (as comment lines with the original line number).
5759 :samp:`new {xxx} [storage_pool = {yyy}]`
5760 Shows the storage pool being used for an allocator.
5763 :samp:`at end {procedure-name};`
5764 Shows the finalization (cleanup) procedure for a scope.
5767 :samp:`(if {expr} then {expr} else {expr})`
5768 Conditional expression equivalent to the ``x?y:z`` construction in C.
5771 :samp:`{target}^({source})`
5772 A conversion with floating-point truncation instead of rounding.
5775 :samp:`{target}?({source})`
5776 A conversion that bypasses normal Ada semantic checking. In particular
5777 enumeration types and fixed-point types are treated simply as integers.
5780 :samp:`{target}?^({source})`
5781 Combines the above two cases.
5786 :samp:`{x} #mod {y}`
5790 :samp:`{x} #rem {y}`
5791 A division or multiplication of fixed-point values which are treated as
5792 integers without any kind of scaling.
5795 :samp:`free {expr} [storage_pool = {xxx}]`
5796 Shows the storage pool associated with a ``free`` statement.
5799 :samp:`[subtype or type declaration]`
5800 Used to list an equivalent declaration for an internally generated
5801 type that is referenced elsewhere in the listing.
5804 :samp:`freeze {type-name} [{actions}]`
5805 Shows the point at which ``type-name`` is frozen, with possible
5806 associated actions to be performed at the freeze point.
5809 :samp:`reference {itype}`
5810 Reference (and hence definition) to internal type ``itype``.
5813 :samp:`{function-name}! ({arg}, {arg}, {arg})`
5814 Intrinsic function call.
5817 :samp:`{label-name} : label`
5818 Declaration of label ``labelname``.
5821 :samp:`#$ {subprogram-name}`
5822 An implicit call to a run-time support routine
5823 (to meet the requirement of H.3.1(9) in a
5827 :samp:`{expr} && {expr} && {expr} ... && {expr}`
5828 A multiple concatenation (same effect as ``expr`` & ``expr`` &
5829 ``expr``, but handled more efficiently).
5832 :samp:`[constraint_error]`
5833 Raise the ``Constraint_Error`` exception.
5836 :samp:`{expression}'reference`
5837 A pointer to the result of evaluating {expression}.
5840 :samp:`{target-type}!({source-expression})`
5841 An unchecked conversion of ``source-expression`` to ``target-type``.
5844 :samp:`[{numerator}/{denominator}]`
5845 Used to represent internal real literals (that) have no exact
5846 representation in base 2-16 (for example, the result of compile time
5847 evaluation of the expression 1.0/27.0).
5850 .. index:: -gnatD (gcc)
5852 :switch:`-gnatD[=nn]`
5853 When used in conjunction with :switch:`-gnatG`, this switch causes
5854 the expanded source, as described above for
5855 :switch:`-gnatG` to be written to files with names
5856 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
5857 instead of to the standard output file. For
5858 example, if the source file name is :file:`hello.adb`, then a file
5859 :file:`hello.adb.dg` will be written. The debugging
5860 information generated by the ``gcc`` :switch:`-g` switch
5861 will refer to the generated :file:`xxx.dg` file. This allows
5862 you to do source level debugging using the generated code which is
5863 sometimes useful for complex code, for example to find out exactly
5864 which part of a complex construction raised an exception. This switch
5865 also suppresses generation of cross-reference information (see
5866 :switch:`-gnatx`) since otherwise the cross-reference information
5867 would refer to the :file:`.dg` file, which would cause
5868 confusion since this is not the original source file.
5870 Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
5871 automatically, so it is not necessary to give both options.
5872 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
5874 .. index:: -gnatL (gcc)
5876 If the switch :switch:`-gnatL` is used in conjunction with
5877 :switch:`-gnatDG`, then the original source lines are interspersed
5878 in the expanded source (as comment lines with the original line number).
5880 The optional parameter ``nn`` if present after -gnatD specifies an
5881 alternative maximum line length that overrides the normal default of 72.
5882 This value is in the range 40-999999, values less than 40 being silently
5883 reset to 40. The equal sign is optional.
5886 .. index:: -gnatr (gcc)
5887 .. index:: pragma Restrictions
5890 This switch causes pragma Restrictions to be treated as Restriction_Warnings
5891 so that violation of restrictions causes warnings rather than illegalities.
5892 This is useful during the development process when new restrictions are added
5893 or investigated. The switch also causes pragma Profile to be treated as
5894 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
5895 restriction warnings rather than restrictions.
5898 .. index:: -gnatR (gcc)
5900 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
5901 This switch controls output from the compiler of a listing showing
5902 representation information for declared types, objects and subprograms.
5903 For :switch:`-gnatR0`, no information is output (equivalent to omitting
5904 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
5905 so :switch:`-gnatR` with no parameter has the same effect), size and
5906 alignment information is listed for declared array and record types.
5908 For :switch:`-gnatR2`, size and alignment information is listed for all
5909 declared types and objects. The ``Linker_Section`` is also listed for any
5910 entity for which the ``Linker_Section`` is set explicitly or implicitly (the
5911 latter case occurs for objects of a type for which a ``Linker_Section``
5914 For :switch:`-gnatR3`, symbolic expressions for values that are computed
5915 at run time for records are included. These symbolic expressions have
5916 a mostly obvious format with #n being used to represent the value of the
5917 n'th discriminant. See source files :file:`repinfo.ads/adb` in the
5918 GNAT sources for full details on the format of :switch:`-gnatR3` output.
5920 For :switch:`-gnatR4`, information for relevant compiler-generated types
5921 is also listed, i.e. when they are structurally part of other declared
5924 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
5925 extended representation information for record sub-components of records
5928 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
5929 subprogram conventions and parameter passing mechanisms for all the
5930 subprograms are included.
5932 If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
5933 the output is in the JSON data interchange format specified by the
5934 ECMA-404 standard. The semantic description of this JSON output is
5935 available in the specification of the Repinfo unit present in the
5938 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
5939 the output is to a file with the name :file:`file.rep` where ``file`` is
5940 the name of the corresponding source file, except if ``j`` is also
5941 specified, in which case the file name is :file:`file.json`.
5943 Note that it is possible for record components to have zero size. In
5944 this case, the component clause uses an obvious extension of permitted
5945 Ada syntax, for example ``at 0 range 0 .. -1``.
5948 .. index:: -gnatS (gcc)
5951 The use of the switch :switch:`-gnatS` for an
5952 Ada compilation will cause the compiler to output a
5953 representation of package Standard in a form very
5954 close to standard Ada. It is not quite possible to
5955 do this entirely in standard Ada (since new
5956 numeric base types cannot be created in standard
5957 Ada), but the output is easily
5958 readable to any Ada programmer, and is useful to
5959 determine the characteristics of target dependent
5960 types in package Standard.
5963 .. index:: -gnatx (gcc)
5966 Normally the compiler generates full cross-referencing information in
5967 the :file:`ALI` file. This information is used by a number of tools,
5968 including ``gnatfind`` and ``gnatxref``. The :switch:`-gnatx` switch
5969 suppresses this information. This saves some space and may slightly
5970 speed up compilation, but means that these tools cannot be used.
5973 .. index:: -fgnat-encodings (gcc)
5975 :switch:`-fgnat-encodings=[all|gdb|minimal]`
5976 This switch controls the balance between GNAT encodings and standard DWARF
5977 emitted in the debug information.
5979 Historically, old debug formats like stabs were not powerful enough to
5980 express some Ada types (for instance, variant records or fixed-point types).
5981 To work around this, GNAT introduced proprietary encodings that embed the
5982 missing information ("GNAT encodings").
5984 Recent versions of the DWARF debug information format are now able to
5985 correctly describe most of these Ada constructs ("standard DWARF"). As
5986 third-party tools started to use this format, GNAT has been enhanced to
5987 generate it. However, most tools (including GDB) are still relying on GNAT
5990 To support all tools, GNAT needs to be versatile about the balance between
5991 generation of GNAT encodings and standard DWARF. This is what
5992 :switch:`-fgnat-encodings` is about.
5994 * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as
5995 possible so it does not conflict with GNAT encodings.
5996 * ``=gdb``: Emit as much standard DWARF as possible as long as the current
5997 GDB handles it. Emit GNAT encodings for the rest.
5998 * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT
5999 encodings for the rest.
6002 .. _Exception_Handling_Control:
6004 Exception Handling Control
6005 --------------------------
6007 GNAT uses two methods for handling exceptions at run time. The
6008 ``setjmp/longjmp`` method saves the context when entering
6009 a frame with an exception handler. Then when an exception is
6010 raised, the context can be restored immediately, without the
6011 need for tracing stack frames. This method provides very fast
6012 exception propagation, but introduces significant overhead for
6013 the use of exception handlers, even if no exception is raised.
6015 The other approach is called 'zero cost' exception handling.
6016 With this method, the compiler builds static tables to describe
6017 the exception ranges. No dynamic code is required when entering
6018 a frame containing an exception handler. When an exception is
6019 raised, the tables are used to control a back trace of the
6020 subprogram invocation stack to locate the required exception
6021 handler. This method has considerably poorer performance for
6022 the propagation of exceptions, but there is no overhead for
6023 exception handlers if no exception is raised. Note that in this
6024 mode and in the context of mixed Ada and C/C++ programming,
6025 to propagate an exception through a C/C++ code, the C/C++ code
6026 must be compiled with the :switch:`-funwind-tables` GCC's
6029 The following switches may be used to control which of the
6030 two exception handling methods is used.
6034 .. index:: --RTS=sjlj (gnatmake)
6036 :switch:`--RTS=sjlj`
6037 This switch causes the setjmp/longjmp run-time (when available) to be used
6038 for exception handling. If the default
6039 mechanism for the target is zero cost exceptions, then
6040 this switch can be used to modify this default, and must be
6041 used for all units in the partition.
6042 This option is rarely used. One case in which it may be
6043 advantageous is if you have an application where exception
6044 raising is common and the overall performance of the
6045 application is improved by favoring exception propagation.
6048 .. index:: --RTS=zcx (gnatmake)
6049 .. index:: Zero Cost Exceptions
6052 This switch causes the zero cost approach to be used
6053 for exception handling. If this is the default mechanism for the
6054 target (see below), then this switch is unneeded. If the default
6055 mechanism for the target is setjmp/longjmp exceptions, then
6056 this switch can be used to modify this default, and must be
6057 used for all units in the partition.
6058 This option can only be used if the zero cost approach
6059 is available for the target in use, otherwise it will generate an error.
6061 The same option :switch:`--RTS` must be used both for ``gcc``
6062 and ``gnatbind``. Passing this option to ``gnatmake``
6063 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
6064 through the compilation and binding steps.
6066 .. _Units_to_Sources_Mapping_Files:
6068 Units to Sources Mapping Files
6069 ------------------------------
6073 .. index:: -gnatem (gcc)
6075 :switch:`-gnatem={path}`
6076 A mapping file is a way to communicate to the compiler two mappings:
6077 from unit names to file names (without any directory information) and from
6078 file names to path names (with full directory information). These mappings
6079 are used by the compiler to short-circuit the path search.
6081 The use of mapping files is not required for correct operation of the
6082 compiler, but mapping files can improve efficiency, particularly when
6083 sources are read over a slow network connection. In normal operation,
6084 you need not be concerned with the format or use of mapping files,
6085 and the :switch:`-gnatem` switch is not a switch that you would use
6086 explicitly. It is intended primarily for use by automatic tools such as
6087 ``gnatmake`` running under the project file facility. The
6088 description here of the format of mapping files is provided
6089 for completeness and for possible use by other tools.
6091 A mapping file is a sequence of sets of three lines. In each set, the
6092 first line is the unit name, in lower case, with ``%s`` appended
6093 for specs and ``%b`` appended for bodies; the second line is the
6094 file name; and the third line is the path name.
6100 /gnat/project1/sources/main.2.ada
6103 When the switch :switch:`-gnatem` is specified, the compiler will
6104 create in memory the two mappings from the specified file. If there is
6105 any problem (nonexistent file, truncated file or duplicate entries),
6106 no mapping will be created.
6108 Several :switch:`-gnatem` switches may be specified; however, only the
6109 last one on the command line will be taken into account.
6111 When using a project file, ``gnatmake`` creates a temporary
6112 mapping file and communicates it to the compiler using this switch.
6115 .. _Code_Generation_Control:
6117 Code Generation Control
6118 -----------------------
6120 The GCC technology provides a wide range of target dependent
6121 :switch:`-m` switches for controlling
6122 details of code generation with respect to different versions of
6123 architectures. This includes variations in instruction sets (e.g.,
6124 different members of the power pc family), and different requirements
6125 for optimal arrangement of instructions (e.g., different members of
6126 the x86 family). The list of available :switch:`-m` switches may be
6127 found in the GCC documentation.
6129 Use of these :switch:`-m` switches may in some cases result in improved
6132 The GNAT technology is tested and qualified without any
6133 :switch:`-m` switches,
6134 so generally the most reliable approach is to avoid the use of these
6135 switches. However, we generally expect most of these switches to work
6136 successfully with GNAT, and many customers have reported successful
6137 use of these options.
6139 Our general advice is to avoid the use of :switch:`-m` switches unless
6140 special needs lead to requirements in this area. In particular,
6141 there is no point in using :switch:`-m` switches to improve performance
6142 unless you actually see a performance improvement.
6145 .. _Linker_Switches:
6150 Linker switches can be specified after :switch:`-largs` builder switch.
6152 .. index:: -fuse-ld=name
6154 :switch:`-fuse-ld={name}`
6155 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`,
6156 the alternative being ``gold`` for :file:`ld.gold`. The later is
6157 a more recent and faster linker, but only available on GNU/Linux
6160 .. _Binding_with_gnatbind:
6162 Binding with ``gnatbind``
6163 =========================
6165 .. index:: ! gnatbind
6167 This chapter describes the GNAT binder, ``gnatbind``, which is used
6168 to bind compiled GNAT objects.
6170 The ``gnatbind`` program performs four separate functions:
6172 * Checks that a program is consistent, in accordance with the rules in
6173 Chapter 10 of the Ada Reference Manual. In particular, error
6174 messages are generated if a program uses inconsistent versions of a
6177 * Checks that an acceptable order of elaboration exists for the program
6178 and issues an error message if it cannot find an order of elaboration
6179 that satisfies the rules in Chapter 10 of the Ada Language Manual.
6181 * Generates a main program incorporating the given elaboration order.
6182 This program is a small Ada package (body and spec) that
6183 must be subsequently compiled
6184 using the GNAT compiler. The necessary compilation step is usually
6185 performed automatically by ``gnatlink``. The two most important
6186 functions of this program
6187 are to call the elaboration routines of units in an appropriate order
6188 and to call the main program.
6190 * Determines the set of object files required by the given main program.
6191 This information is output in the forms of comments in the generated program,
6192 to be read by the ``gnatlink`` utility used to link the Ada application.
6194 .. _Running_gnatbind:
6196 Running ``gnatbind``
6197 --------------------
6199 The form of the ``gnatbind`` command is
6203 $ gnatbind [ switches ] mainprog[.ali] [ switches ]
6206 where :file:`mainprog.adb` is the Ada file containing the main program
6207 unit body. ``gnatbind`` constructs an Ada
6208 package in two files whose names are
6209 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
6210 For example, if given the
6211 parameter :file:`hello.ali`, for a main program contained in file
6212 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
6213 and :file:`b~hello.adb`.
6215 When doing consistency checking, the binder takes into consideration
6216 any source files it can locate. For example, if the binder determines
6217 that the given main program requires the package ``Pack``, whose
6219 file is :file:`pack.ali` and whose corresponding source spec file is
6220 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
6221 (using the same search path conventions as previously described for the
6222 ``gcc`` command). If it can locate this source file, it checks that
6224 or source checksums of the source and its references to in :file:`ALI` files
6225 match. In other words, any :file:`ALI` files that mentions this spec must have
6226 resulted from compiling this version of the source file (or in the case
6227 where the source checksums match, a version close enough that the
6228 difference does not matter).
6230 .. index:: Source files, use by binder
6232 The effect of this consistency checking, which includes source files, is
6233 that the binder ensures that the program is consistent with the latest
6234 version of the source files that can be located at bind time. Editing a
6235 source file without compiling files that depend on the source file cause
6236 error messages to be generated by the binder.
6238 For example, suppose you have a main program :file:`hello.adb` and a
6239 package ``P``, from file :file:`p.ads` and you perform the following
6242 * Enter ``gcc -c hello.adb`` to compile the main program.
6244 * Enter ``gcc -c p.ads`` to compile package ``P``.
6246 * Edit file :file:`p.ads`.
6248 * Enter ``gnatbind hello``.
6250 At this point, the file :file:`p.ali` contains an out-of-date time stamp
6251 because the file :file:`p.ads` has been edited. The attempt at binding
6252 fails, and the binder generates the following error messages:
6257 error: "hello.adb" must be recompiled ("p.ads" has been modified)
6258 error: "p.ads" has been modified and must be recompiled
6261 Now both files must be recompiled as indicated, and then the bind can
6262 succeed, generating a main program. You need not normally be concerned
6263 with the contents of this file, but for reference purposes a sample
6264 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6266 In most normal usage, the default mode of ``gnatbind`` which is to
6267 generate the main package in Ada, as described in the previous section.
6268 In particular, this means that any Ada programmer can read and understand
6269 the generated main program. It can also be debugged just like any other
6270 Ada code provided the :switch:`-g` switch is used for
6271 ``gnatbind`` and ``gnatlink``.
6273 .. _Switches_for_gnatbind:
6275 Switches for ``gnatbind``
6276 -------------------------
6278 The following switches are available with ``gnatbind``; details will
6279 be presented in subsequent sections.
6282 .. index:: --version (gnatbind)
6285 Display Copyright and version, then exit disregarding all other options.
6288 .. index:: --help (gnatbind)
6291 If :switch:`--version` was not used, display usage, then exit disregarding
6295 .. index:: -a (gnatbind)
6298 Indicates that, if supported by the platform, the adainit procedure should
6299 be treated as an initialisation routine by the linker (a constructor). This
6300 is intended to be used by the Project Manager to automatically initialize
6301 shared Stand-Alone Libraries.
6304 .. index:: -aO (gnatbind)
6307 Specify directory to be searched for ALI files.
6310 .. index:: -aI (gnatbind)
6313 Specify directory to be searched for source file.
6316 .. index:: -A (gnatbind)
6318 :switch:`-A[={filename}]`
6319 Output ALI list (to standard output or to the named file).
6322 .. index:: -b (gnatbind)
6325 Generate brief messages to :file:`stderr` even if verbose mode set.
6328 .. index:: -c (gnatbind)
6331 Check only, no generation of binder output file.
6334 .. index:: -dnn[k|m] (gnatbind)
6336 :switch:`-d{nn}[k|m]`
6337 This switch can be used to change the default task stack size value
6338 to a specified size ``nn``, which is expressed in bytes by default, or
6339 in kilobytes when suffixed with ``k`` or in megabytes when suffixed
6341 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6342 in effect, to completing all task specs with
6346 pragma Storage_Size (nn);
6348 When they do not already have such a pragma.
6351 .. index:: -D (gnatbind)
6353 :switch:`-D{nn}[k|m]`
6354 Set the default secondary stack size to ``nn``. The suffix indicates whether
6355 the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
6358 The secondary stack holds objects of unconstrained types that are returned by
6359 functions, for example unconstrained Strings. The size of the secondary stack
6360 can be dynamic or fixed depending on the target.
6362 For most targets, the secondary stack grows on demand and is implemented as
6363 a chain of blocks in the heap. In this case, the default secondary stack size
6364 determines the initial size of the secondary stack for each task and the
6365 smallest amount the secondary stack can grow by.
6367 For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
6368 fixed. This switch can be used to change the default size of these stacks.
6369 The default secondary stack size can be overridden on a per-task basis if
6370 individual tasks have different secondary stack requirements. This is
6371 achieved through the Secondary_Stack_Size aspect that takes the size of the
6372 secondary stack in bytes.
6374 .. index:: -e (gnatbind)
6377 Output complete list of elaboration-order dependencies.
6380 .. index:: -Ea (gnatbind)
6383 Store tracebacks in exception occurrences when the target supports it.
6384 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6385 unless symbolic tracebacks are enabled.
6387 See also the packages ``GNAT.Traceback`` and
6388 ``GNAT.Traceback.Symbolic`` for more information.
6389 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
6393 .. index:: -Es (gnatbind)
6396 Store tracebacks in exception occurrences when the target supports it.
6397 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6400 .. index:: -E (gnatbind)
6403 Currently the same as ``-Ea``.
6406 .. index:: -f (gnatbind)
6408 :switch:`-f{elab-order}`
6409 Force elaboration order. For further details see :ref:`Elaboration_Control`
6410 and :ref:`Elaboration_Order_Handling_in_GNAT`.
6413 .. index:: -F (gnatbind)
6416 Force the checks of elaboration flags. ``gnatbind`` does not normally
6417 generate checks of elaboration flags for the main executable, except when
6418 a Stand-Alone Library is used. However, there are cases when this cannot be
6419 detected by gnatbind. An example is importing an interface of a Stand-Alone
6420 Library through a pragma Import and only specifying through a linker switch
6421 this Stand-Alone Library. This switch is used to guarantee that elaboration
6422 flag checks are generated.
6425 .. index:: -h (gnatbind)
6428 Output usage (help) information.
6431 .. index:: -H (gnatbind)
6434 Legacy elaboration order model enabled. For further details see
6435 :ref:`Elaboration_Order_Handling_in_GNAT`.
6438 .. index:: -H32 (gnatbind)
6441 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
6442 For further details see :ref:`Dynamic_Allocation_Control`.
6445 .. index:: -H64 (gnatbind)
6446 .. index:: __gnat_malloc
6449 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
6450 For further details see :ref:`Dynamic_Allocation_Control`.
6453 .. index:: -I (gnatbind)
6456 Specify directory to be searched for source and ALI files.
6459 .. index:: -I- (gnatbind)
6462 Do not look for sources in the current directory where ``gnatbind`` was
6463 invoked, and do not look for ALI files in the directory containing the
6464 ALI file named in the ``gnatbind`` command line.
6467 .. index:: -l (gnatbind)
6470 Output chosen elaboration order.
6473 .. index:: -L (gnatbind)
6476 Bind the units for library building. In this case the ``adainit`` and
6477 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6478 are renamed to :samp:`{xxx}init` and
6481 (:ref:`GNAT_and_Libraries`, for more details.)
6484 .. index:: -M (gnatbind)
6487 Rename generated main program from main to xyz. This option is
6488 supported on cross environments only.
6490 .. index:: -m (gnatbind)
6493 Limit number of detected errors or warnings to ``n``, where ``n`` is
6494 in the range 1..999999. The default value if no switch is
6495 given is 9999. If the number of warnings reaches this limit, then a
6496 message is output and further warnings are suppressed, the bind
6497 continues in this case. If the number of errors reaches this
6498 limit, then a message is output and the bind is abandoned.
6499 A value of zero means that no limit is enforced. The equal
6502 .. index:: -minimal (gnatbind)
6505 Generate a binder file suitable for space-constrained applications. When
6506 active, binder-generated objects not required for program operation are no
6507 longer generated. **Warning:** this option comes with the following
6510 * Starting the program's execution in the debugger will cause it to
6511 stop at the start of the ``main`` function instead of the main subprogram.
6512 This can be worked around by manually inserting a breakpoint on that
6513 subprogram and resuming the program's execution until reaching that breakpoint.
6514 * Programs using GNAT.Compiler_Version will not link.
6516 .. index:: -n (gnatbind)
6522 .. index:: -nostdinc (gnatbind)
6525 Do not look for sources in the system default directory.
6528 .. index:: -nostdlib (gnatbind)
6531 Do not look for library files in the system default directory.
6534 .. index:: --RTS (gnatbind)
6536 :switch:`--RTS={rts-path}`
6537 Specifies the default location of the run-time library. Same meaning as the
6538 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
6540 .. index:: -o (gnatbind)
6543 Name the output file ``file`` (default is :file:`b~`xxx`.adb`).
6544 Note that if this option is used, then linking must be done manually,
6545 gnatlink cannot be used.
6548 .. index:: -O (gnatbind)
6550 :switch:`-O[={filename}]`
6551 Output object list (to standard output or to the named file).
6554 .. index:: -p (gnatbind)
6557 Pessimistic (worst-case) elaboration order.
6560 .. index:: -P (gnatbind)
6563 Generate binder file suitable for CodePeer.
6566 .. index:: -R (gnatbind)
6569 Output closure source list, which includes all non-run-time units that are
6570 included in the bind.
6573 .. index:: -Ra (gnatbind)
6576 Like :switch:`-R` but the list includes run-time units.
6579 .. index:: -s (gnatbind)
6582 Require all source files to be present.
6585 .. index:: -S (gnatbind)
6588 Specifies the value to be used when detecting uninitialized scalar
6589 objects with pragma Initialize_Scalars.
6590 The ``xxx`` string specified with the switch is one of:
6592 * ``in`` for an invalid value.
6594 If zero is invalid for the discrete type in question,
6595 then the scalar value is set to all zero bits.
6596 For signed discrete types, the largest possible negative value of
6597 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6598 For unsigned discrete types, the underlying scalar value is set to all
6599 one bits. For floating-point types, a NaN value is set
6600 (see body of package System.Scalar_Values for exact values).
6602 * ``lo`` for low value.
6604 If zero is invalid for the discrete type in question,
6605 then the scalar value is set to all zero bits.
6606 For signed discrete types, the largest possible negative value of
6607 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6608 For unsigned discrete types, the underlying scalar value is set to all
6609 zero bits. For floating-point, a small value is set
6610 (see body of package System.Scalar_Values for exact values).
6612 * ``hi`` for high value.
6614 If zero is invalid for the discrete type in question,
6615 then the scalar value is set to all one bits.
6616 For signed discrete types, the largest possible positive value of
6617 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6618 For unsigned discrete types, the underlying scalar value is set to all
6619 one bits. For floating-point, a large value is set
6620 (see body of package System.Scalar_Values for exact values).
6622 * ``xx`` for hex value (two hex digits).
6624 The underlying scalar is set to a value consisting of repeated bytes, whose
6625 value corresponds to the given value. For example if ``BF`` is given,
6626 then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``.
6628 .. index:: GNAT_INIT_SCALARS
6630 In addition, you can specify :switch:`-Sev` to indicate that the value is
6631 to be set at run time. In this case, the program will look for an environment
6632 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
6633 of :samp:`in/lo/hi/{xx}` with the same meanings as above.
6634 If no environment variable is found, or if it does not have a valid value,
6635 then the default is ``in`` (invalid values).
6637 .. index:: -static (gnatbind)
6640 Link against a static GNAT run-time.
6643 .. index:: -shared (gnatbind)
6646 Link against a shared GNAT run-time when available.
6649 .. index:: -t (gnatbind)
6652 Tolerate time stamp and other consistency errors.
6655 .. index:: -T (gnatbind)
6658 Set the time slice value to ``n`` milliseconds. If the system supports
6659 the specification of a specific time slice value, then the indicated value
6660 is used. If the system does not support specific time slice values, but
6661 does support some general notion of round-robin scheduling, then any
6662 nonzero value will activate round-robin scheduling.
6664 A value of zero is treated specially. It turns off time
6665 slicing, and in addition, indicates to the tasking run-time that the
6666 semantics should match as closely as possible the Annex D
6667 requirements of the Ada RM, and in particular sets the default
6668 scheduling policy to ``FIFO_Within_Priorities``.
6671 .. index:: -u (gnatbind)
6674 Enable dynamic stack usage, with ``n`` results stored and displayed
6675 at program termination. A result is generated when a task
6676 terminates. Results that can't be stored are displayed on the fly, at
6677 task termination. This option is currently not supported on Itanium
6678 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6681 .. index:: -v (gnatbind)
6684 Verbose mode. Write error messages, header, summary output to
6688 .. index:: -V (gnatbind)
6690 :switch:`-V{key}={value}`
6691 Store the given association of ``key`` to ``value`` in the bind environment.
6692 Values stored this way can be retrieved at run time using
6693 ``GNAT.Bind_Environment``.
6696 .. index:: -w (gnatbind)
6699 Warning mode; ``x`` = s/e for suppress/treat as error.
6702 .. index:: -Wx (gnatbind)
6705 Override default wide character encoding for standard Text_IO files.
6708 .. index:: -x (gnatbind)
6711 Exclude source files (check object consistency only).
6714 .. index:: -Xnnn (gnatbind)
6717 Set default exit status value, normally 0 for POSIX compliance.
6720 .. index:: -y (gnatbind)
6723 Enable leap seconds support in ``Ada.Calendar`` and its children.
6726 .. index:: -z (gnatbind)
6731 You may obtain this listing of switches by running ``gnatbind`` with
6735 .. _Consistency-Checking_Modes:
6737 Consistency-Checking Modes
6738 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6740 As described earlier, by default ``gnatbind`` checks
6741 that object files are consistent with one another and are consistent
6742 with any source files it can locate. The following switches control binder
6746 .. index:: -s (gnatbind)
6749 Require source files to be present. In this mode, the binder must be
6750 able to locate all source files that are referenced, in order to check
6751 their consistency. In normal mode, if a source file cannot be located it
6752 is simply ignored. If you specify this switch, a missing source
6756 .. index:: -Wx (gnatbind)
6759 Override default wide character encoding for standard Text_IO files.
6760 Normally the default wide character encoding method used for standard
6761 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6762 the main source input (see description of switch
6763 :switch:`-gnatWx` for the compiler). The
6764 use of this switch for the binder (which has the same set of
6765 possible arguments) overrides this default as specified.
6768 .. index:: -x (gnatbind)
6771 Exclude source files. In this mode, the binder only checks that ALI
6772 files are consistent with one another. Source files are not accessed.
6773 The binder runs faster in this mode, and there is still a guarantee that
6774 the resulting program is self-consistent.
6775 If a source file has been edited since it was last compiled, and you
6776 specify this switch, the binder will not detect that the object
6777 file is out of date with respect to the source file. Note that this is the
6778 mode that is automatically used by ``gnatmake`` because in this
6779 case the checking against sources has already been performed by
6780 ``gnatmake`` in the course of compilation (i.e., before binding).
6783 .. _Binder_Error_Message_Control:
6785 Binder Error Message Control
6786 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6788 The following switches provide control over the generation of error
6789 messages from the binder:
6793 .. index:: -v (gnatbind)
6796 Verbose mode. In the normal mode, brief error messages are generated to
6797 :file:`stderr`. If this switch is present, a header is written
6798 to :file:`stdout` and any error messages are directed to :file:`stdout`.
6799 All that is written to :file:`stderr` is a brief summary message.
6802 .. index:: -b (gnatbind)
6805 Generate brief error messages to :file:`stderr` even if verbose mode is
6806 specified. This is relevant only when used with the
6807 :switch:`-v` switch.
6810 .. index:: -m (gnatbind)
6813 Limits the number of error messages to ``n``, a decimal integer in the
6814 range 1-999. The binder terminates immediately if this limit is reached.
6817 .. index:: -M (gnatbind)
6820 Renames the generated main program from ``main`` to ``xxx``.
6821 This is useful in the case of some cross-building environments, where
6822 the actual main program is separate from the one generated
6826 .. index:: -ws (gnatbind)
6830 Suppress all warning messages.
6833 .. index:: -we (gnatbind)
6836 Treat any warning messages as fatal errors.
6839 .. index:: -t (gnatbind)
6840 .. index:: Time stamp checks, in binder
6841 .. index:: Binder consistency checks
6842 .. index:: Consistency checks, in binder
6845 The binder performs a number of consistency checks including:
6848 * Check that time stamps of a given source unit are consistent
6850 * Check that checksums of a given source unit are consistent
6852 * Check that consistent versions of ``GNAT`` were used for compilation
6854 * Check consistency of configuration pragmas as required
6856 Normally failure of such checks, in accordance with the consistency
6857 requirements of the Ada Reference Manual, causes error messages to be
6858 generated which abort the binder and prevent the output of a binder
6859 file and subsequent link to obtain an executable.
6861 The :switch:`-t` switch converts these error messages
6862 into warnings, so that
6863 binding and linking can continue to completion even in the presence of such
6864 errors. The result may be a failed link (due to missing symbols), or a
6865 non-functional executable which has undefined semantics.
6869 This means that :switch:`-t` should be used only in unusual situations,
6872 .. _Elaboration_Control:
6877 The following switches provide additional control over the elaboration
6878 order. For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
6881 .. index:: -f (gnatbind)
6883 :switch:`-f{elab-order}`
6884 Force elaboration order.
6886 ``elab-order`` should be the name of a "forced elaboration order file", that
6887 is, a text file containing library item names, one per line. A name of the
6888 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
6889 name of the form "some.unit%b" or "some.unit (body)" denotes the body of
6890 Some.Unit. Each pair of lines is taken to mean that there is an elaboration
6891 dependence of the second line on the first. For example, if the file
6901 then the spec of This will be elaborated before the body of This, and the
6902 body of This will be elaborated before the spec of That, and the spec of That
6903 will be elaborated before the body of That. The first and last of these three
6904 dependences are already required by Ada rules, so this file is really just
6905 forcing the body of This to be elaborated before the spec of That.
6907 The given order must be consistent with Ada rules, or else ``gnatbind`` will
6908 give elaboration cycle errors. For example, if you say x (body) should be
6909 elaborated before x (spec), there will be a cycle, because Ada rules require
6910 x (spec) to be elaborated before x (body); you can't have the spec and body
6911 both elaborated before each other.
6913 If you later add "with That;" to the body of This, there will be a cycle, in
6914 which case you should erase either "this (body)" or "that (spec)" from the
6915 above forced elaboration order file.
6917 Blank lines and Ada-style comments are ignored. Unit names that do not exist
6918 in the program are ignored. Units in the GNAT predefined library are also
6922 .. index:: -p (gnatbind)
6925 Pessimistic elaboration order
6927 This switch is only applicable to the pre-20.x legacy elaboration models.
6928 The post-20.x elaboration model uses a more informed approach of ordering
6931 Normally the binder attempts to choose an elaboration order that is likely to
6932 minimize the likelihood of an elaboration order error resulting in raising a
6933 ``Program_Error`` exception. This switch reverses the action of the binder,
6934 and requests that it deliberately choose an order that is likely to maximize
6935 the likelihood of an elaboration error. This is useful in ensuring
6936 portability and avoiding dependence on accidental fortuitous elaboration
6939 Normally it only makes sense to use the :switch:`-p` switch if dynamic
6940 elaboration checking is used (:switch:`-gnatE` switch used for compilation).
6941 This is because in the default static elaboration mode, all necessary
6942 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
6943 These implicit pragmas are still respected by the binder in :switch:`-p`
6944 mode, so a safe elaboration order is assured.
6946 Note that :switch:`-p` is not intended for production use; it is more for
6947 debugging/experimental use.
6954 The following switches allow additional control over the output
6955 generated by the binder.
6958 .. index:: -c (gnatbind)
6961 Check only. Do not generate the binder output file. In this mode the
6962 binder performs all error checks but does not generate an output file.
6965 .. index:: -e (gnatbind)
6968 Output complete list of elaboration-order dependencies, showing the
6969 reason for each dependency. This output can be rather extensive but may
6970 be useful in diagnosing problems with elaboration order. The output is
6971 written to :file:`stdout`.
6974 .. index:: -h (gnatbind)
6977 Output usage information. The output is written to :file:`stdout`.
6980 .. index:: -K (gnatbind)
6983 Output linker options to :file:`stdout`. Includes library search paths,
6984 contents of pragmas Ident and Linker_Options, and libraries added
6988 .. index:: -l (gnatbind)
6991 Output chosen elaboration order. The output is written to :file:`stdout`.
6994 .. index:: -O (gnatbind)
6997 Output full names of all the object files that must be linked to provide
6998 the Ada component of the program. The output is written to :file:`stdout`.
6999 This list includes the files explicitly supplied and referenced by the user
7000 as well as implicitly referenced run-time unit files. The latter are
7001 omitted if the corresponding units reside in shared libraries. The
7002 directory names for the run-time units depend on the system configuration.
7005 .. index:: -o (gnatbind)
7008 Set name of output file to ``file`` instead of the normal
7009 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
7010 binder generated body filename.
7011 Note that if this option is used, then linking must be done manually.
7012 It is not possible to use gnatlink in this case, since it cannot locate
7016 .. index:: -r (gnatbind)
7019 Generate list of ``pragma Restrictions`` that could be applied to
7020 the current unit. This is useful for code audit purposes, and also may
7021 be used to improve code generation in some cases.
7024 .. _Dynamic_Allocation_Control:
7026 Dynamic Allocation Control
7027 ^^^^^^^^^^^^^^^^^^^^^^^^^^
7029 The heap control switches -- :switch:`-H32` and :switch:`-H64` --
7030 determine whether dynamic allocation uses 32-bit or 64-bit memory.
7031 They only affect compiler-generated allocations via ``__gnat_malloc``;
7032 explicit calls to ``malloc`` and related functions from the C
7033 run-time library are unaffected.
7036 Allocate memory on 32-bit heap
7040 Allocate memory on 64-bit heap. This is the default
7041 unless explicitly overridden by a ``'Size`` clause on the access type.
7043 These switches are only effective on VMS platforms.
7046 .. _Binding_with_Non-Ada_Main_Programs:
7048 Binding with Non-Ada Main Programs
7049 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7051 The description so far has assumed that the main
7052 program is in Ada, and that the task of the binder is to generate a
7053 corresponding function ``main`` that invokes this Ada main
7054 program. GNAT also supports the building of executable programs where
7055 the main program is not in Ada, but some of the called routines are
7056 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
7057 The following switch is used in this situation:
7060 .. index:: -n (gnatbind)
7063 No main program. The main program is not in Ada.
7065 In this case, most of the functions of the binder are still required,
7066 but instead of generating a main program, the binder generates a file
7067 containing the following callable routines:
7072 You must call this routine to initialize the Ada part of the program by
7073 calling the necessary elaboration routines. A call to ``adainit`` is
7074 required before the first call to an Ada subprogram.
7076 Note that it is assumed that the basic execution environment must be setup
7077 to be appropriate for Ada execution at the point where the first Ada
7078 subprogram is called. In particular, if the Ada code will do any
7079 floating-point operations, then the FPU must be setup in an appropriate
7080 manner. For the case of the x86, for example, full precision mode is
7081 required. The procedure GNAT.Float_Control.Reset may be used to ensure
7082 that the FPU is in the right state.
7087 You must call this routine to perform any library-level finalization
7088 required by the Ada subprograms. A call to ``adafinal`` is required
7089 after the last call to an Ada subprogram, and before the program
7092 .. index:: -n (gnatbind)
7093 .. index:: Binder, multiple input files
7095 If the :switch:`-n` switch
7096 is given, more than one ALI file may appear on
7097 the command line for ``gnatbind``. The normal ``closure``
7098 calculation is performed for each of the specified units. Calculating
7099 the closure means finding out the set of units involved by tracing
7100 |with| references. The reason it is necessary to be able to
7101 specify more than one ALI file is that a given program may invoke two or
7102 more quite separate groups of Ada units.
7104 The binder takes the name of its output file from the last specified ALI
7105 file, unless overridden by the use of the :switch:`-o file`.
7107 .. index:: -o (gnatbind)
7109 The output is an Ada unit in source form that can be compiled with GNAT.
7110 This compilation occurs automatically as part of the ``gnatlink``
7113 Currently the GNAT run-time requires a FPU using 80 bits mode
7114 precision. Under targets where this is not the default it is required to
7115 call GNAT.Float_Control.Reset before using floating point numbers (this
7116 include float computation, float input and output) in the Ada code. A
7117 side effect is that this could be the wrong mode for the foreign code
7118 where floating point computation could be broken after this call.
7121 .. _Binding_Programs_with_No_Main_Subprogram:
7123 Binding Programs with No Main Subprogram
7124 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7126 It is possible to have an Ada program which does not have a main
7127 subprogram. This program will call the elaboration routines of all the
7128 packages, then the finalization routines.
7130 The following switch is used to bind programs organized in this manner:
7132 .. index:: -z (gnatbind)
7135 Normally the binder checks that the unit name given on the command line
7136 corresponds to a suitable main subprogram. When this switch is used,
7137 a list of ALI files can be given, and the execution of the program
7138 consists of elaboration of these units in an appropriate order. Note
7139 that the default wide character encoding method for standard Text_IO
7140 files is always set to Brackets if this switch is set (you can use
7142 :switch:`-Wx` to override this default).
7145 .. _Command-Line_Access:
7150 The package ``Ada.Command_Line`` provides access to the command-line
7151 arguments and program name. In order for this interface to operate
7152 correctly, the two variables
7159 .. index:: gnat_argv
7160 .. index:: gnat_argc
7162 are declared in one of the GNAT library routines. These variables must
7163 be set from the actual ``argc`` and ``argv`` values passed to the
7164 main program. With no *n* present, ``gnatbind``
7165 generates the C main program to automatically set these variables.
7166 If the *n* switch is used, there is no automatic way to
7167 set these variables. If they are not set, the procedures in
7168 ``Ada.Command_Line`` will not be available, and any attempt to use
7169 them will raise ``Constraint_Error``. If command line access is
7170 required, your main program must set ``gnat_argc`` and
7171 ``gnat_argv`` from the ``argc`` and ``argv`` values passed to
7175 .. _Search_Paths_for_gnatbind:
7177 Search Paths for ``gnatbind``
7178 -----------------------------
7180 The binder takes the name of an ALI file as its argument and needs to
7181 locate source files as well as other ALI files to verify object consistency.
7183 For source files, it follows exactly the same search rules as ``gcc``
7184 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
7185 directories searched are:
7187 * The directory containing the ALI file named in the command line, unless
7188 the switch :switch:`-I-` is specified.
7190 * All directories specified by :switch:`-I`
7191 switches on the ``gnatbind``
7192 command line, in the order given.
7194 .. index:: ADA_PRJ_OBJECTS_FILE
7196 * Each of the directories listed in the text file whose name is given
7197 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
7199 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
7200 driver when project files are used. It should not normally be set
7203 .. index:: ADA_OBJECTS_PATH
7205 * Each of the directories listed in the value of the
7206 :envvar:`ADA_OBJECTS_PATH` environment variable.
7207 Construct this value
7208 exactly as the :envvar:`PATH` environment variable: a list of directory
7209 names separated by colons (semicolons when working with the NT version
7212 * The content of the :file:`ada_object_path` file which is part of the GNAT
7213 installation tree and is used to store standard libraries such as the
7214 GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
7215 specified. See :ref:`Installing_a_library`
7217 .. index:: -I (gnatbind)
7218 .. index:: -aI (gnatbind)
7219 .. index:: -aO (gnatbind)
7221 In the binder the switch :switch:`-I`
7222 is used to specify both source and
7223 library file paths. Use :switch:`-aI`
7224 instead if you want to specify
7225 source paths only, and :switch:`-aO`
7226 if you want to specify library paths
7227 only. This means that for the binder
7228 :switch:`-I{dir}` is equivalent to
7230 :switch:`-aO`{dir}`.
7231 The binder generates the bind file (a C language source file) in the
7232 current working directory.
7236 .. index:: Interfaces
7239 The packages ``Ada``, ``System``, and ``Interfaces`` and their
7240 children make up the GNAT Run-Time Library, together with the package
7241 GNAT and its children, which contain a set of useful additional
7242 library functions provided by GNAT. The sources for these units are
7243 needed by the compiler and are kept together in one directory. The ALI
7244 files and object files generated by compiling the RTL are needed by the
7245 binder and the linker and are kept together in one directory, typically
7246 different from the directory containing the sources. In a normal
7247 installation, you need not specify these directory names when compiling
7248 or binding. Either the environment variables or the built-in defaults
7249 cause these files to be found.
7251 Besides simplifying access to the RTL, a major use of search paths is
7252 in compiling sources from multiple directories. This can make
7253 development environments much more flexible.
7256 .. _Examples_of_gnatbind_Usage:
7258 Examples of ``gnatbind`` Usage
7259 ------------------------------
7261 Here are some examples of ``gnatbind`` invovations:
7267 The main program ``Hello`` (source program in :file:`hello.adb`) is
7268 bound using the standard switch settings. The generated main program is
7269 :file:`b~hello.adb`. This is the normal, default use of the binder.
7273 gnatbind hello -o mainprog.adb
7275 The main program ``Hello`` (source program in :file:`hello.adb`) is
7276 bound using the standard switch settings. The generated main program is
7277 :file:`mainprog.adb` with the associated spec in
7278 :file:`mainprog.ads`. Note that you must specify the body here not the
7279 spec. Note that if this option is used, then linking must be done manually,
7280 since gnatlink will not be able to find the generated file.
7283 .. _Linking_with_gnatlink:
7285 Linking with ``gnatlink``
7286 =========================
7288 .. index:: ! gnatlink
7290 This chapter discusses ``gnatlink``, a tool that links
7291 an Ada program and builds an executable file. This utility
7292 invokes the system linker (via the ``gcc`` command)
7293 with a correct list of object files and library references.
7294 ``gnatlink`` automatically determines the list of files and
7295 references for the Ada part of a program. It uses the binder file
7296 generated by the ``gnatbind`` to determine this list.
7298 .. _Running_gnatlink:
7300 Running ``gnatlink``
7301 --------------------
7303 The form of the ``gnatlink`` command is
7308 $ gnatlink [ switches ] mainprog [.ali]
7309 [ non-Ada objects ] [ linker options ]
7313 The arguments of ``gnatlink`` (switches, main ``ALI`` file,
7315 or linker options) may be in any order, provided that no non-Ada object may
7316 be mistaken for a main :file:`ALI` file.
7317 Any file name :file:`F` without the :file:`.ali`
7318 extension will be taken as the main :file:`ALI` file if a file exists
7319 whose name is the concatenation of :file:`F` and :file:`.ali`.
7321 :file:`mainprog.ali` references the ALI file of the main program.
7322 The :file:`.ali` extension of this file can be omitted. From this
7323 reference, ``gnatlink`` locates the corresponding binder file
7324 :file:`b~mainprog.adb` and, using the information in this file along
7325 with the list of non-Ada objects and linker options, constructs a
7326 linker command file to create the executable.
7328 The arguments other than the ``gnatlink`` switches and the main
7329 :file:`ALI` file are passed to the linker uninterpreted.
7330 They typically include the names of
7331 object files for units written in other languages than Ada and any library
7332 references required to resolve references in any of these foreign language
7333 units, or in ``Import`` pragmas in any Ada units.
7335 ``linker options`` is an optional list of linker specific
7337 The default linker called by gnatlink is ``gcc`` which in
7338 turn calls the appropriate system linker.
7340 One useful option for the linker is :switch:`-s`: it reduces the size of the
7341 executable by removing all symbol table and relocation information from the
7344 Standard options for the linker such as :switch:`-lmy_lib` or
7345 :switch:`-Ldir` can be added as is.
7346 For options that are not recognized by
7347 ``gcc`` as linker options, use the ``gcc`` switches
7348 :switch:`-Xlinker` or :switch:`-Wl,`.
7350 Refer to the GCC documentation for
7353 Here is an example showing how to generate a linker map:
7357 $ gnatlink my_prog -Wl,-Map,MAPFILE
7360 Using ``linker options`` it is possible to set the program stack and
7362 See :ref:`Setting_Stack_Size_from_gnatlink` and
7363 :ref:`Setting_Heap_Size_from_gnatlink`.
7365 ``gnatlink`` determines the list of objects required by the Ada
7366 program and prepends them to the list of objects passed to the linker.
7367 ``gnatlink`` also gathers any arguments set by the use of
7368 ``pragma Linker_Options`` and adds them to the list of arguments
7369 presented to the linker.
7372 .. _Switches_for_gnatlink:
7374 Switches for ``gnatlink``
7375 -------------------------
7377 The following switches are available with the ``gnatlink`` utility:
7379 .. index:: --version (gnatlink)
7382 Display Copyright and version, then exit disregarding all other options.
7385 .. index:: --help (gnatlink)
7388 If :switch:`--version` was not used, display usage, then exit disregarding
7392 .. index:: Command line length
7393 .. index:: -f (gnatlink)
7396 On some targets, the command line length is limited, and ``gnatlink``
7397 will generate a separate file for the linker if the list of object files
7399 The :switch:`-f` switch forces this file
7400 to be generated even if
7401 the limit is not exceeded. This is useful in some cases to deal with
7402 special situations where the command line length is exceeded.
7405 .. index:: Debugging information, including
7406 .. index:: -g (gnatlink)
7409 The option to include debugging information causes the Ada bind file (in
7410 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
7411 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7412 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7413 Without :switch:`-g`, the binder removes these files by default.
7415 .. index:: -n (gnatlink)
7418 Do not compile the file generated by the binder. This may be used when
7419 a link is rerun with different options, but there is no need to recompile
7423 .. index:: -v (gnatlink)
7426 Verbose mode. Causes additional information to be output, including a full
7427 list of the included object files.
7428 This switch option is most useful when you want
7429 to see what set of object files are being used in the link step.
7432 .. index:: -v -v (gnatlink)
7435 Very verbose mode. Requests that the compiler operate in verbose mode when
7436 it compiles the binder file, and that the system linker run in verbose mode.
7439 .. index:: -o (gnatlink)
7441 :switch:`-o {exec-name}`
7442 ``exec-name`` specifies an alternate name for the generated
7443 executable program. If this switch is omitted, the executable has the same
7444 name as the main unit. For example, ``gnatlink try.ali`` creates
7445 an executable called :file:`try`.
7448 .. index:: -B (gnatlink)
7451 Load compiler executables (for example, ``gnat1``, the Ada compiler)
7452 from ``dir`` instead of the default location. Only use this switch
7453 when multiple versions of the GNAT compiler are available.
7454 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
7455 for further details. You would normally use the :switch:`-b` or
7456 :switch:`-V` switch instead.
7459 .. index:: -M (gnatlink)
7462 When linking an executable, create a map file. The name of the map file
7463 has the same name as the executable with extension ".map".
7466 .. index:: -M= (gnatlink)
7468 :switch:`-M={mapfile}`
7469 When linking an executable, create a map file. The name of the map file is
7473 .. index:: --GCC=compiler_name (gnatlink)
7475 :switch:`--GCC={compiler_name}`
7476 Program used for compiling the binder file. The default is
7477 ``gcc``. You need to use quotes around ``compiler_name`` if
7478 ``compiler_name`` contains spaces or other separator characters.
7479 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
7480 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7481 inserted after your command name. Thus in the above example the compiler
7482 command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
7483 A limitation of this syntax is that the name and path name of the executable
7484 itself must not include any embedded spaces. If the compiler executable is
7485 different from the default one (gcc or <prefix>-gcc), then the back-end
7486 switches in the ALI file are not used to compile the binder generated source.
7487 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7488 switches will be used for ``--GCC="gcc -gnatv"``. If several
7489 ``--GCC=compiler_name`` are used, only the last ``compiler_name``
7490 is taken into account. However, all the additional switches are also taken
7492 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7493 ``--GCC="bar -x -y -z -t"``.
7496 .. index:: --LINK= (gnatlink)
7498 :switch:`--LINK={name}`
7499 ``name`` is the name of the linker to be invoked. This is especially
7500 useful in mixed language programs since languages such as C++ require
7501 their own linker to be used. When this switch is omitted, the default
7502 name for the linker is ``gcc``. When this switch is used, the
7503 specified linker is called instead of ``gcc`` with exactly the same
7504 parameters that would have been passed to ``gcc`` so if the desired
7505 linker requires different parameters it is necessary to use a wrapper
7506 script that massages the parameters before invoking the real linker. It
7507 may be useful to control the exact invocation by using the verbose
7511 .. _Using_the_GNU_make_Utility:
7513 Using the GNU ``make`` Utility
7514 ==============================
7516 .. index:: make (GNU), GNU make
7518 This chapter offers some examples of makefiles that solve specific
7519 problems. It does not explain how to write a makefile, nor does it try to replace the
7520 ``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7522 All the examples in this section are specific to the GNU version of
7523 make. Although ``make`` is a standard utility, and the basic language
7524 is the same, these examples use some advanced features found only in
7527 .. _Using_gnatmake_in_a_Makefile:
7529 Using gnatmake in a Makefile
7530 ----------------------------
7532 .. index makefile (GNU make)
7534 Complex project organizations can be handled in a very powerful way by
7535 using GNU make combined with gnatmake. For instance, here is a Makefile
7536 which allows you to build each subsystem of a big project into a separate
7537 shared library. Such a makefile allows you to significantly reduce the link
7538 time of very big applications while maintaining full coherence at
7539 each step of the build process.
7541 The list of dependencies are handled automatically by
7542 ``gnatmake``. The Makefile is simply used to call gnatmake in each of
7543 the appropriate directories.
7545 Note that you should also read the example on how to automatically
7546 create the list of directories
7547 (:ref:`Automatically_Creating_a_List_of_Directories`)
7548 which might help you in case your project has a lot of subdirectories.
7551 .. code-block:: makefile
7553 ## This Makefile is intended to be used with the following directory
7555 ## - The sources are split into a series of csc (computer software components)
7556 ## Each of these csc is put in its own directory.
7557 ## Their name are referenced by the directory names.
7558 ## They will be compiled into shared library (although this would also work
7559 ## with static libraries
7560 ## - The main program (and possibly other packages that do not belong to any
7561 ## csc is put in the top level directory (where the Makefile is).
7562 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7563 ## \\_ second_csc (sources) __ lib (will contain the library)
7565 ## Although this Makefile is build for shared library, it is easy to modify
7566 ## to build partial link objects instead (modify the lines with -shared and
7569 ## With this makefile, you can change any file in the system or add any new
7570 ## file, and everything will be recompiled correctly (only the relevant shared
7571 ## objects will be recompiled, and the main program will be re-linked).
7573 # The list of computer software component for your project. This might be
7574 # generated automatically.
7577 # Name of the main program (no extension)
7580 # If we need to build objects with -fPIC, uncomment the following line
7583 # The following variable should give the directory containing libgnat.so
7584 # You can get this directory through 'gnatls -v'. This is usually the last
7585 # directory in the Object_Path.
7588 # The directories for the libraries
7589 # (This macro expands the list of CSC to the list of shared libraries, you
7590 # could simply use the expanded form:
7591 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7592 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7594 ${MAIN}: objects ${LIB_DIR}
7595 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7596 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7599 # recompile the sources
7600 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7602 # Note: In a future version of GNAT, the following commands will be simplified
7603 # by a new tool, gnatmlib
7606 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7607 cd ${dir $@ } && cp -f ../*.ali .
7609 # The dependencies for the modules
7610 # Note that we have to force the expansion of *.o, since in some cases
7611 # make won't be able to do it itself.
7612 aa/lib/libaa.so: ${wildcard aa/*.o}
7613 bb/lib/libbb.so: ${wildcard bb/*.o}
7614 cc/lib/libcc.so: ${wildcard cc/*.o}
7616 # Make sure all of the shared libraries are in the path before starting the
7619 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7622 ${RM} -rf ${CSC_LIST:%=%/lib}
7623 ${RM} ${CSC_LIST:%=%/*.ali}
7624 ${RM} ${CSC_LIST:%=%/*.o}
7625 ${RM} *.o *.ali ${MAIN}
7628 .. _Automatically_Creating_a_List_of_Directories:
7630 Automatically Creating a List of Directories
7631 --------------------------------------------
7633 In most makefiles, you will have to specify a list of directories, and
7634 store it in a variable. For small projects, it is often easier to
7635 specify each of them by hand, since you then have full control over what
7636 is the proper order for these directories, which ones should be
7639 However, in larger projects, which might involve hundreds of
7640 subdirectories, it might be more convenient to generate this list
7643 The example below presents two methods. The first one, although less
7644 general, gives you more control over the list. It involves wildcard
7645 characters, that are automatically expanded by ``make``. Its
7646 shortcoming is that you need to explicitly specify some of the
7647 organization of your project, such as for instance the directory tree
7648 depth, whether some directories are found in a separate tree, etc.
7650 The second method is the most general one. It requires an external
7651 program, called ``find``, which is standard on all Unix systems. All
7652 the directories found under a given root directory will be added to the
7655 .. code-block:: makefile
7657 # The examples below are based on the following directory hierarchy:
7658 # All the directories can contain any number of files
7659 # ROOT_DIRECTORY -> a -> aa -> aaa
7665 # This Makefile creates a variable called DIRS, that can be reused any time
7666 # you need this list (see the other examples in this section)
7668 # The root of your project's directory hierarchy
7672 # First method: specify explicitly the list of directories
7673 # This allows you to specify any subset of all the directories you need.
7676 DIRS := a/aa/ a/ab/ b/ba/
7679 # Second method: use wildcards
7680 # Note that the argument(s) to wildcard below should end with a '/'.
7681 # Since wildcards also return file names, we have to filter them out
7682 # to avoid duplicate directory names.
7683 # We thus use make's ``dir`` and ``sort`` functions.
7684 # It sets DIRs to the following value (note that the directories aaa and baa
7685 # are not given, unless you change the arguments to wildcard).
7686 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7689 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7690 ${ROOT_DIRECTORY}/*/*/}}}
7693 # Third method: use an external program
7694 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7695 # This is the most complete command: it sets DIRs to the following value:
7696 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7699 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7703 .. _Generating_the_Command_Line_Switches:
7705 Generating the Command Line Switches
7706 ------------------------------------
7708 Once you have created the list of directories as explained in the
7709 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7710 you can easily generate the command line arguments to pass to gnatmake.
7712 For the sake of completeness, this example assumes that the source path
7713 is not the same as the object path, and that you have two separate lists
7716 .. code-block:: makefile
7718 # see "Automatically creating a list of directories" to create
7723 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7724 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7727 gnatmake ${GNATMAKE_SWITCHES} main_unit
7730 .. _Overcoming_Command_Line_Length_Limits:
7732 Overcoming Command Line Length Limits
7733 -------------------------------------
7735 One problem that might be encountered on big projects is that many
7736 operating systems limit the length of the command line. It is thus hard to give
7737 gnatmake the list of source and object directories.
7739 This example shows how you can set up environment variables, which will
7740 make ``gnatmake`` behave exactly as if the directories had been
7741 specified on the command line, but have a much higher length limit (or
7742 even none on most systems).
7744 It assumes that you have created a list of directories in your Makefile,
7745 using one of the methods presented in
7746 :ref:`Automatically_Creating_a_List_of_Directories`.
7747 For the sake of completeness, we assume that the object
7748 path (where the ALI files are found) is different from the sources patch.
7750 Note a small trick in the Makefile below: for efficiency reasons, we
7751 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7752 expanded immediately by ``make``. This way we overcome the standard
7753 make behavior which is to expand the variables only when they are
7756 On Windows, if you are using the standard Windows command shell, you must
7757 replace colons with semicolons in the assignments to these variables.
7759 .. code-block:: makefile
7761 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7762 # This is the same thing as putting the -I arguments on the command line.
7763 # (the equivalent of using -aI on the command line would be to define
7764 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
7765 # You can of course have different values for these variables.
7767 # Note also that we need to keep the previous values of these variables, since
7768 # they might have been set before running 'make' to specify where the GNAT
7769 # library is installed.
7771 # see "Automatically creating a list of directories" to create these
7777 space:=${empty} ${empty}
7778 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
7779 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
7780 ADA_INCLUDE_PATH += ${SOURCE_LIST}
7781 ADA_OBJECTS_PATH += ${OBJECT_LIST}
7782 export ADA_INCLUDE_PATH
7783 export ADA_OBJECTS_PATH