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`).
31 .. _The_GNAT_Make_Program_gnatmake:
33 Building with *gnatmake*
34 ========================
38 A typical development cycle when working on an Ada program consists of
41 #. Edit some sources to fix bugs;
45 #. Compile all sources affected;
47 #. Rebind and relink; and
51 .. index:: Dependency rules (compilation)
53 The third step in particular can be tricky, because not only do the modified
54 files have to be compiled, but any files depending on these files must also be
55 recompiled. The dependency rules in Ada can be quite complex, especially
56 in the presence of overloading, `use` clauses, generics and inlined
59 *gnatmake* automatically takes care of the third and fourth steps
60 of this process. It determines which sources need to be compiled,
61 compiles them, and binds and links the resulting object files.
63 Unlike some other Ada make programs, the dependencies are always
64 accurately recomputed from the new sources. The source based approach of
65 the GNAT compilation model makes this possible. This means that if
66 changes to the source program cause corresponding changes in
67 dependencies, they will always be tracked exactly correctly by
70 Note that for advanced description of project structure, we recommend creating
71 a project file as explained in :ref:`GNAT_Project_Manager` and use the
72 *gprbuild* tool which supports building with project files and works similarly
80 The usual form of the *gnatmake* command is
84 $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
86 The only required argument is one `file_name`, which specifies
87 a compilation unit that is a main program. Several `file_names` can be
88 specified: this will result in several executables being built.
89 If `switches` are present, they can be placed before the first
90 `file_name`, between `file_names` or after the last `file_name`.
91 If `mode_switches` are present, they must always be placed after
92 the last `file_name` and all `switches`.
94 If you are using standard file extensions (:file:`.adb` and
95 :file:`.ads`), then the
96 extension may be omitted from the `file_name` arguments. However, if
97 you are using non-standard extensions, then it is required that the
98 extension be given. A relative or absolute directory path can be
99 specified in a `file_name`, in which case, the input source file will
100 be searched for in the specified directory only. Otherwise, the input
101 source file will first be searched in the directory where
102 *gnatmake* was invoked and if it is not found, it will be search on
103 the source path of the compiler as described in
104 :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
106 All *gnatmake* output (except when you specify *-M*) is sent to
107 :file:`stderr`. The output produced by the
108 *-M* switch is sent to :file:`stdout`.
111 .. _Switches_for_gnatmake:
113 Switches for *gnatmake*
114 -----------------------
116 You may specify any of the following switches to *gnatmake*:
119 .. index:: --version (gnatmake)
122 Display Copyright and version, then exit disregarding all other options.
125 .. index:: --help (gnatmake)
128 If ``--version`` was not used, display usage, then exit disregarding
132 .. index:: --GCC=compiler_name (gnatmake)
134 :samp:`--GCC={compiler_name}`
135 Program used for compiling. The default is ``gcc``. You need to use
136 quotes around `compiler_name` if `compiler_name` contains
137 spaces or other separator characters.
138 As an example ``--GCC="foo -x -y"``
139 will instruct *gnatmake* to use ``foo -x -y`` as your
140 compiler. A limitation of this syntax is that the name and path name of
141 the executable itself must not include any embedded spaces. Note that
142 switch ``-c`` is always inserted after your command name. Thus in the
143 above example the compiler command that will be used by *gnatmake*
144 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
145 used, only the last `compiler_name` is taken into account. However,
146 all the additional switches are also taken into account. Thus,
147 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
148 ``--GCC="bar -x -y -z -t"``.
151 .. index:: --GNATBIND=binder_name (gnatmake)
153 :samp:`--GNATBIND={binder_name}`
154 Program used for binding. The default is ``gnatbind``. You need to
155 use quotes around `binder_name` if `binder_name` contains spaces
156 or other separator characters.
157 As an example ``--GNATBIND="bar -x -y"``
158 will instruct *gnatmake* to use `bar -x -y` as your
159 binder. Binder switches that are normally appended by *gnatmake*
160 to ``gnatbind`` are now appended to the end of `bar -x -y`.
161 A limitation of this syntax is that the name and path name of the executable
162 itself must not include any embedded spaces.
164 .. index:: --GNATLINK=linker_name (gnatmake)
166 :samp:`--GNATLINK={linker_name}`
167 Program used for linking. The default is ``gnatlink``. You need to
168 use quotes around `linker_name` if `linker_name` contains spaces
169 or other separator characters.
170 As an example ``--GNATLINK="lan -x -y"``
171 will instruct *gnatmake* to use ``lan -x -y`` as your
172 linker. Linker switches that are normally appended by ``gnatmake`` to
173 ``gnatlink`` are now appended to the end of ``lan -x -y``.
174 A limitation of this syntax is that the name and path name of the executable
175 itself must not include any embedded spaces.
177 :samp:`--create-map-file`
178 When linking an executable, create a map file. The name of the map file
179 has the same name as the executable with extension ".map".
181 :samp:`--create-map-file={mapfile}`
182 When linking an executable, create a map file with the specified name.
184 .. index:: --create-missing-dirs (gnatmake)
186 :samp:`--create-missing-dirs`
187 When using project files (:samp:`-P{project}`), automatically create
188 missing object directories, library directories and exec
191 :samp:`--single-compile-per-obj-dir`
192 Disallow simultaneous compilations in the same object directory when
193 project files are used.
195 :samp:`--subdirs={subdir}`
196 Actual object directory of each project file is the subdirectory subdir of the
197 object directory specified or defaulted in the project file.
199 :samp:`--unchecked-shared-lib-imports`
200 By default, shared library projects are not allowed to import static library
201 projects. When this switch is used on the command line, this restriction is
204 :samp:`--source-info={source info file}`
205 Specify a source info file. This switch is active only when project files
206 are used. If the source info file is specified as a relative path, then it is
207 relative to the object directory of the main project. If the source info file
208 does not exist, then after the Project Manager has successfully parsed and
209 processed the project files and found the sources, it creates the source info
210 file. If the source info file already exists and can be read successfully,
211 then the Project Manager will get all the needed information about the sources
212 from the source info file and will not look for them. This reduces the time
213 to process the project files, especially when looking for sources that take a
214 long time. If the source info file exists but cannot be parsed successfully,
215 the Project Manager will attempt to recreate it. If the Project Manager fails
216 to create the source info file, a message is issued, but gnatmake does not
217 fail. *gnatmake* "trusts" the source info file. This means that
218 if the source files have changed (addition, deletion, moving to a different
219 source directory), then the source info file need to be deleted and recreated.
222 .. index:: -a (gnatmake)
225 Consider all files in the make process, even the GNAT internal system
226 files (for example, the predefined Ada library files), as well as any
227 locked files. Locked files are files whose ALI file is write-protected.
229 *gnatmake* does not check these files,
230 because the assumption is that the GNAT internal files are properly up
231 to date, and also that any write protected ALI files have been properly
232 installed. Note that if there is an installation problem, such that one
233 of these files is not up to date, it will be properly caught by the
235 You may have to specify this switch if you are working on GNAT
236 itself. The switch ``-a`` is also useful
237 in conjunction with ``-f``
238 if you need to recompile an entire application,
239 including run-time files, using special configuration pragmas,
240 such as a `Normalize_Scalars` pragma.
243 ``gnatmake -a`` compiles all GNAT
245 ``gcc -c -gnatpg`` rather than ``gcc -c``.
248 .. index:: -b (gnatmake)
251 Bind only. Can be combined with *-c* to do
252 compilation and binding, but no link.
253 Can be combined with *-l*
254 to do binding and linking. When not combined with
256 all the units in the closure of the main program must have been previously
257 compiled and must be up to date. The root unit specified by `file_name`
258 may be given without extension, with the source extension or, if no GNAT
259 Project File is specified, with the ALI file extension.
262 .. index:: -c (gnatmake)
265 Compile only. Do not perform binding, except when *-b*
266 is also specified. Do not perform linking, except if both
268 *-l* are also specified.
269 If the root unit specified by `file_name` is not a main unit, this is the
270 default. Otherwise *gnatmake* will attempt binding and linking
271 unless all objects are up to date and the executable is more recent than
275 .. index:: -C (gnatmake)
278 Use a temporary mapping file. A mapping file is a way to communicate
279 to the compiler two mappings: from unit names to file names (without
280 any directory information) and from file names to path names (with
281 full directory information). A mapping file can make the compiler's
282 file searches faster, especially if there are many source directories,
283 or the sources are read over a slow network connection. If
284 *-P* is used, a mapping file is always used, so
285 *-C* is unnecessary; in this case the mapping file
286 is initially populated based on the project file. If
289 the mapping file is initially empty. Each invocation of the compiler
290 will add any newly accessed sources to the mapping file.
293 .. index:: -C= (gnatmake)
296 Use a specific mapping file. The file, specified as a path name (absolute or
297 relative) by this switch, should already exist, otherwise the switch is
298 ineffective. The specified mapping file will be communicated to the compiler.
299 This switch is not compatible with a project file
300 (-P`file`) or with multiple compiling processes
301 (-jnnn, when nnn is greater than 1).
304 .. index:: -d (gnatmake)
307 Display progress for each source, up to date or not, as a single line:
311 completed x out of y (zz%)
313 If the file needs to be compiled this is displayed after the invocation of
314 the compiler. These lines are displayed even in quiet output mode.
317 .. index:: -D (gnatmake)
320 Put all object files and ALI file in directory `dir`.
321 If the *-D* switch is not used, all object files
322 and ALI files go in the current working directory.
324 This switch cannot be used when using a project file.
327 .. index:: -eI (gnatmake)
330 Indicates that the main source is a multi-unit source and the rank of the unit
331 in the source file is nnn. nnn needs to be a positive number and a valid
332 index in the source. This switch cannot be used when *gnatmake* is
333 invoked for several mains.
336 .. index:: -eL (gnatmake)
337 .. index:: symbolic links
340 Follow all symbolic links when processing project files.
341 This should be used if your project uses symbolic links for files or
342 directories, but is not needed in other cases.
344 .. index:: naming scheme
346 This also assumes that no directory matches the naming scheme for files (for
347 instance that you do not have a directory called "sources.ads" when using the
348 default GNAT naming scheme).
350 When you do not have to use this switch (i.e., by default), gnatmake is able to
351 save a lot of system calls (several per source file and object file), which
352 can result in a significant speed up to load and manipulate a project file,
353 especially when using source files from a remote system.
356 .. index:: -eS (gnatmake)
359 Output the commands for the compiler, the binder and the linker
361 instead of standard error.
364 .. index:: -f (gnatmake)
367 Force recompilations. Recompile all sources, even though some object
368 files may be up to date, but don't recompile predefined or GNAT internal
369 files or locked files (files with a write-protected ALI file),
370 unless the *-a* switch is also specified.
373 .. index:: -F (gnatmake)
376 When using project files, if some errors or warnings are detected during
377 parsing and verbose mode is not in effect (no use of switch
378 -v), then error lines start with the full path name of the project
379 file, rather than its simple file name.
382 .. index:: -g (gnatmake)
385 Enable debugging. This switch is simply passed to the compiler and to the
389 .. index:: -i (gnatmake)
392 In normal mode, *gnatmake* compiles all object files and ALI files
393 into the current directory. If the *-i* switch is used,
394 then instead object files and ALI files that already exist are overwritten
395 in place. This means that once a large project is organized into separate
396 directories in the desired manner, then *gnatmake* will automatically
397 maintain and update this organization. If no ALI files are found on the
398 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
399 the new object and ALI files are created in the
400 directory containing the source being compiled. If another organization
401 is desired, where objects and sources are kept in different directories,
402 a useful technique is to create dummy ALI files in the desired directories.
403 When detecting such a dummy file, *gnatmake* will be forced to
404 recompile the corresponding source file, and it will be put the resulting
405 object and ALI files in the directory where it found the dummy file.
408 .. index:: -j (gnatmake)
409 .. index:: Parallel make
412 Use `n` processes to carry out the (re)compilations. On a multiprocessor
413 machine compilations will occur in parallel. If `n` is 0, then the
414 maximum number of parallel compilations is the number of core processors
415 on the platform. In the event of compilation errors, messages from various
416 compilations might get interspersed (but *gnatmake* will give you the
417 full ordered list of failing compiles at the end). If this is problematic,
418 rerun the make process with n set to 1 to get a clean list of messages.
421 .. index:: -k (gnatmake)
424 Keep going. Continue as much as possible after a compilation error. To
425 ease the programmer's task in case of compilation errors, the list of
426 sources for which the compile fails is given when *gnatmake*
429 If *gnatmake* is invoked with several :file:`file_names` and with this
430 switch, if there are compilation errors when building an executable,
431 *gnatmake* will not attempt to build the following executables.
434 .. index:: -l (gnatmake)
437 Link only. Can be combined with *-b* to binding
438 and linking. Linking will not be performed if combined with
441 When not combined with *-b*
442 all the units in the closure of the main program must have been previously
443 compiled and must be up to date, and the main program needs to have been bound.
444 The root unit specified by `file_name`
445 may be given without extension, with the source extension or, if no GNAT
446 Project File is specified, with the ALI file extension.
449 .. index:: -m (gnatmake)
452 Specify that the minimum necessary amount of recompilations
453 be performed. In this mode *gnatmake* ignores time
454 stamp differences when the only
455 modifications to a source file consist in adding/removing comments,
456 empty lines, spaces or tabs. This means that if you have changed the
457 comments in a source file or have simply reformatted it, using this
458 switch will tell *gnatmake* not to recompile files that depend on it
459 (provided other sources on which these files depend have undergone no
460 semantic modifications). Note that the debugging information may be
461 out of date with respect to the sources if the *-m* switch causes
462 a compilation to be switched, so the use of this switch represents a
463 trade-off between compilation time and accurate debugging information.
466 .. index:: Dependencies, producing list
467 .. index:: -M (gnatmake)
470 Check if all objects are up to date. If they are, output the object
471 dependences to :file:`stdout` in a form that can be directly exploited in
472 a :file:`Makefile`. By default, each source file is prefixed with its
473 (relative or absolute) directory name. This name is whatever you
474 specified in the various *-aI*
475 and *-I* switches. If you use
477 (see below), only the source file names,
478 without relative paths, are output. If you just specify the *-M*
479 switch, dependencies of the GNAT internal system files are omitted. This
480 is typically what you want. If you also specify
482 dependencies of the GNAT internal files are also listed. Note that
483 dependencies of the objects in external Ada libraries (see
484 switch :samp:`-aL{dir}` in the following list)
488 .. index:: -n (gnatmake)
491 Don't compile, bind, or link. Checks if all objects are up to date.
492 If they are not, the full name of the first file that needs to be
493 recompiled is printed.
494 Repeated use of this option, followed by compiling the indicated source
495 file, will eventually result in recompiling all required units.
498 .. index:: -o (gnatmake)
500 :samp:`-o {exec_name}`
501 Output executable name. The name of the final executable program will be
502 `exec_name`. If the *-o* switch is omitted the default
503 name for the executable will be the name of the input file in appropriate form
504 for an executable file on the host system.
506 This switch cannot be used when invoking *gnatmake* with several
510 .. index:: -p (gnatmake)
513 Same as :samp:`--create-missing-dirs`
515 .. index:: -P (gnatmake)
518 Use project file `project`. Only one such switch can be used.
519 :ref:`gnatmake_and_Project_Files`.
522 .. index:: -q (gnatmake)
525 Quiet. When this flag is not set, the commands carried out by
526 *gnatmake* are displayed.
529 .. index:: -s (gnatmake)
532 Recompile if compiler switches have changed since last compilation.
533 All compiler switches but -I and -o are taken into account in the
535 orders between different 'first letter' switches are ignored, but
536 orders between same switches are taken into account. For example,
537 *-O -O2* is different than *-O2 -O*, but *-g -O*
538 is equivalent to *-O -g*.
540 This switch is recommended when Integrated Preprocessing is used.
543 .. index:: -u (gnatmake)
546 Unique. Recompile at most the main files. It implies -c. Combined with
547 -f, it is equivalent to calling the compiler directly. Note that using
548 -u with a project file and no main has a special meaning
549 (:ref:`Project_Files_and_Main_Subprograms`).
552 .. index:: -U (gnatmake)
555 When used without a project file or with one or several mains on the command
556 line, is equivalent to -u. When used with a project file and no main
557 on the command line, all sources of all project files are checked and compiled
558 if not up to date, and libraries are rebuilt, if necessary.
561 .. index:: -v (gnatmake)
564 Verbose. Display the reason for all recompilations *gnatmake*
565 decides are necessary, with the highest verbosity level.
568 .. index:: -vl (gnatmake)
571 Verbosity level Low. Display fewer lines than in verbosity Medium.
574 .. index:: -vm (gnatmake)
577 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
580 .. index:: -vm (gnatmake)
583 Verbosity level High. Equivalent to -v.
587 Indicate the verbosity of the parsing of GNAT project files.
588 See :ref:`Switches_Related_to_Project_Files`.
591 .. index:: -x (gnatmake)
594 Indicate that sources that are not part of any Project File may be compiled.
595 Normally, when using Project Files, only sources that are part of a Project
596 File may be compile. When this switch is used, a source outside of all Project
597 Files may be compiled. The ALI file and the object file will be put in the
598 object directory of the main Project. The compilation switches used will only
599 be those specified on the command line. Even when
600 *-x* is used, mains specified on the
601 command line need to be sources of a project file.
604 :samp:`-X{name}={value}`
605 Indicate that external variable `name` has the value `value`.
606 The Project Manager will use this value for occurrences of
607 `external(name)` when parsing the project file.
608 :ref:`Switches_Related_to_Project_Files`.
611 .. index:: -z (gnatmake)
614 No main subprogram. Bind and link the program even if the unit name
615 given on the command line is a package name. The resulting executable
616 will execute the elaboration routines of the package and its closure,
617 then the finalization routines.
620 .. rubric:: GCC switches
622 Any uppercase or multi-character switch that is not a *gnatmake* switch
623 is passed to *gcc* (e.g., *-O*, *-gnato,* etc.)
626 .. rubric:: Source and library search path switches
628 .. index:: -aI (gnatmake)
631 When looking for source files also look in directory `dir`.
632 The order in which source files search is undertaken is
633 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
636 .. index:: -aL (gnatmake)
639 Consider `dir` as being an externally provided Ada library.
640 Instructs *gnatmake* to skip compilation units whose :file:`.ALI`
641 files have been located in directory `dir`. This allows you to have
642 missing bodies for the units in `dir` and to ignore out of date bodies
643 for the same units. You still need to specify
644 the location of the specs for these units by using the switches
645 :samp:`-aI{dir}` or :samp:`-I{dir}`.
646 Note: this switch is provided for compatibility with previous versions
647 of *gnatmake*. The easier method of causing standard libraries
648 to be excluded from consideration is to write-protect the corresponding
652 .. index:: -aO (gnatmake)
655 When searching for library and object files, look in directory
656 `dir`. The order in which library files are searched is described in
657 :ref:`Search_Paths_for_gnatbind`.
660 .. index:: Search paths, for gnatmake
661 .. index:: -A (gnatmake)
664 Equivalent to :samp:`-aL{dir}` :samp:`-aI{dir}`.
667 .. index:: -I (gnatmake)
670 Equivalent to :samp:`-aO{dir} -aI{dir}`.
673 .. index:: -I- (gnatmake)
674 .. index:: Source files, suppressing search
677 Do not look for source files in the directory containing the source
678 file named in the command line.
679 Do not look for ALI or object files in the directory
680 where *gnatmake* was invoked.
683 .. index:: -L (gnatmake)
684 .. index:: Linker libraries
687 Add directory `dir` to the list of directories in which the linker
688 will search for libraries. This is equivalent to
689 :samp:`-largs` :samp:`-L{dir}`.
690 Furthermore, under Windows, the sources pointed to by the libraries path
691 set in the registry are not searched for.
694 .. index:: -nostdinc (gnatmake)
697 Do not look for source files in the system default directory.
700 .. index:: -nostdlib (gnatmake)
703 Do not look for library files in the system default directory.
706 .. index:: --RTS (gnatmake)
708 :samp:`--RTS={rts-path}`
709 Specifies the default location of the runtime library. GNAT looks for the
711 in the following directories, and stops as soon as a valid runtime is found
712 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
713 :file:`ada_object_path` present):
715 * *<current directory>/$rts_path*
717 * *<default-search-dir>/$rts_path*
719 * *<default-search-dir>/rts-$rts_path*
721 * The selected path is handled like a normal RTS path.
724 .. _Mode_Switches_for_gnatmake:
726 Mode Switches for *gnatmake*
727 ----------------------------
729 The mode switches (referred to as `mode_switches`) allow the
730 inclusion of switches that are to be passed to the compiler itself, the
731 binder or the linker. The effect of a mode switch is to cause all
732 subsequent switches up to the end of the switch list, or up to the next
733 mode switch, to be interpreted as switches to be passed on to the
734 designated component of GNAT.
736 .. index:: -cargs (gnatmake)
738 :samp:`-cargs {switches}`
739 Compiler switches. Here `switches` is a list of switches
740 that are valid switches for *gcc*. They will be passed on to
741 all compile steps performed by *gnatmake*.
744 .. index:: -bargs (gnatmake)
746 :samp:`-bargs {switches}`
747 Binder switches. Here `switches` is a list of switches
748 that are valid switches for `gnatbind`. They will be passed on to
749 all bind steps performed by *gnatmake*.
752 .. index:: -largs (gnatmake)
754 :samp:`-largs {switches}`
755 Linker switches. Here `switches` is a list of switches
756 that are valid switches for *gnatlink*. They will be passed on to
757 all link steps performed by *gnatmake*.
760 .. index:: -margs (gnatmake)
762 :samp:`-margs {switches}`
763 Make switches. The switches are directly interpreted by *gnatmake*,
764 regardless of any previous occurrence of *-cargs*, *-bargs*
768 .. _Notes_on_the_Command_Line:
770 Notes on the Command Line
771 -------------------------
773 This section contains some additional useful notes on the operation
774 of the *gnatmake* command.
776 .. index:: Recompilation (by gnatmake)
778 * If *gnatmake* finds no ALI files, it recompiles the main program
779 and all other units required by the main program.
780 This means that *gnatmake*
781 can be used for the initial compile, as well as during subsequent steps of
782 the development cycle.
784 * If you enter ``gnatmake foo.adb``, where ``foo``
785 is a subunit or body of a generic unit, *gnatmake* recompiles
786 :file:`foo.adb` (because it finds no ALI) and stops, issuing a
789 * In *gnatmake* the switch *-I*
790 is used to specify both source and
791 library file paths. Use *-aI*
792 instead if you just want to specify
793 source paths only and *-aO*
794 if you want to specify library paths
797 * *gnatmake* will ignore any files whose ALI file is write-protected.
798 This may conveniently be used to exclude standard libraries from
799 consideration and in particular it means that the use of the
800 *-f* switch will not recompile these files
801 unless *-a* is also specified.
803 * *gnatmake* has been designed to make the use of Ada libraries
804 particularly convenient. Assume you have an Ada library organized
805 as follows: *obj-dir* contains the objects and ALI files for
806 of your Ada compilation units,
807 whereas *include-dir* contains the
808 specs of these units, but no bodies. Then to compile a unit
809 stored in `main.adb`, which uses this Ada library you would just type:
813 $ gnatmake -aI`include-dir` -aL`obj-dir` main
815 * Using *gnatmake* along with the *-m (minimal recompilation)*
816 switch provides a mechanism for avoiding unnecessary recompilations. Using
818 you can update the comments/format of your
819 source files without having to recompile everything. Note, however, that
820 adding or deleting lines in a source files may render its debugging
821 info obsolete. If the file in question is a spec, the impact is rather
822 limited, as that debugging info will only be useful during the
823 elaboration phase of your program. For bodies the impact can be more
824 significant. In all events, your debugger will warn you if a source file
825 is more recent than the corresponding object, and alert you to the fact
826 that the debugging information may be out of date.
829 .. _How_gnatmake_Works:
834 Generally *gnatmake* automatically performs all necessary
835 recompilations and you don't need to worry about how it works. However,
836 it may be useful to have some basic understanding of the *gnatmake*
837 approach and in particular to understand how it uses the results of
838 previous compilations without incorrectly depending on them.
840 First a definition: an object file is considered *up to date* if the
841 corresponding ALI file exists and if all the source files listed in the
842 dependency section of this ALI file have time stamps matching those in
843 the ALI file. This means that neither the source file itself nor any
844 files that it depends on have been modified, and hence there is no need
845 to recompile this file.
847 *gnatmake* works by first checking if the specified main unit is up
848 to date. If so, no compilations are required for the main unit. If not,
849 *gnatmake* compiles the main program to build a new ALI file that
850 reflects the latest sources. Then the ALI file of the main unit is
851 examined to find all the source files on which the main program depends,
852 and *gnatmake* recursively applies the above procedure on all these
855 This process ensures that *gnatmake* only trusts the dependencies
856 in an existing ALI file if they are known to be correct. Otherwise it
857 always recompiles to determine a new, guaranteed accurate set of
858 dependencies. As a result the program is compiled 'upside down' from what may
859 be more familiar as the required order of compilation in some other Ada
860 systems. In particular, clients are compiled before the units on which
861 they depend. The ability of GNAT to compile in any order is critical in
862 allowing an order of compilation to be chosen that guarantees that
863 *gnatmake* will recompute a correct set of new dependencies if
866 When invoking *gnatmake* with several `file_names`, if a unit is
867 imported by several of the executables, it will be recompiled at most once.
869 Note: when using non-standard naming conventions
870 (:ref:`Using_Other_File_Names`), changing through a configuration pragmas
871 file the version of a source and invoking *gnatmake* to recompile may
872 have no effect, if the previous version of the source is still accessible
873 by *gnatmake*. It may be necessary to use the switch
877 .. _Examples_of_gnatmake_Usage:
879 Examples of *gnatmake* Usage
880 ----------------------------
883 Compile all files necessary to bind and link the main program
884 :file:`hello.adb` (containing unit `Hello`) and bind and link the
885 resulting object files to generate an executable file :file:`hello`.
887 *gnatmake main1 main2 main3*
888 Compile all files necessary to bind and link the main programs
889 :file:`main1.adb` (containing unit `Main1`), :file:`main2.adb`
890 (containing unit `Main2`) and :file:`main3.adb`
891 (containing unit `Main3`) and bind and link the resulting object files
892 to generate three executable files :file:`main1`,
893 :file:`main2` and :file:`main3`.
895 *gnatmake -q Main_Unit -cargs -O2 -bargs -l*
896 Compile all files necessary to bind and link the main program unit
897 `Main_Unit` (from file :file:`main_unit.adb`). All compilations will
898 be done with optimization level 2 and the order of elaboration will be
899 listed by the binder. *gnatmake* will operate in quiet mode, not
900 displaying commands it is executing.
903 .. _Compiling_with_gcc:
908 This section discusses how to compile Ada programs using the *gcc*
909 command. It also describes the set of switches
910 that can be used to control the behavior of the compiler.
912 .. _Compiling_Programs:
917 The first step in creating an executable program is to compile the units
918 of the program using the *gcc* command. You must compile the
921 * the body file (:file:`.adb`) for a library level subprogram or generic
924 * the spec file (:file:`.ads`) for a library level package or generic
925 package that has no body
927 * the body file (:file:`.adb`) for a library level package
928 or generic package that has a body
930 You need *not* compile the following files
932 * the spec of a library unit which has a body
936 because they are compiled as part of compiling related units. GNAT
938 when the corresponding body is compiled, and subunits when the parent is
941 .. index:: cannot generate code
943 If you attempt to compile any of these files, you will get one of the
944 following error messages (where `fff` is the name of the file you
949 cannot generate code for file `fff` (package spec)
950 to check package spec, use -gnatc
952 cannot generate code for file `fff` (missing subunits)
953 to check parent unit, use -gnatc
955 cannot generate code for file `fff` (subprogram spec)
956 to check subprogram spec, use -gnatc
958 cannot generate code for file `fff` (subunit)
959 to check subunit, use -gnatc
962 As indicated by the above error messages, if you want to submit
963 one of these files to the compiler to check for correct semantics
964 without generating code, then use the *-gnatc* switch.
966 The basic command for compiling a file containing an Ada unit is:
970 $ gcc -c [switches] <file name>
972 where `file name` is the name of the Ada file (usually
973 having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
975 :option:`-c` switch to tell *gcc* to compile, but not link, the file.
976 The result of a successful compilation is an object file, which has the
977 same name as the source file but an extension of :file:`.o` and an Ada
978 Library Information (ALI) file, which also has the same name as the
979 source file, but with :file:`.ali` as the extension. GNAT creates these
980 two output files in the current directory, but you may specify a source
981 file in any directory using an absolute or relative path specification
982 containing the directory information.
986 *gcc* is actually a driver program that looks at the extensions of
987 the file arguments and loads the appropriate compiler. For example, the
988 GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`.
989 These programs are in directories known to the driver program (in some
990 configurations via environment variables you set), but need not be in
991 your path. The *gcc* driver also calls the assembler and any other
992 utilities needed to complete the generation of the required object
995 It is possible to supply several file names on the same *gcc*
996 command. This causes *gcc* to call the appropriate compiler for
997 each file. For example, the following command lists two separate
998 files to be compiled:
1002 $ gcc -c x.adb y.adb
1005 calls `gnat1` (the Ada compiler) twice to compile :file:`x.adb` and
1007 The compiler generates two object files :file:`x.o` and :file:`y.o`
1008 and the two ALI files :file:`x.ali` and :file:`y.ali`.
1010 Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a
1011 list of available *gcc* switches.
1013 .. _Search_Paths_and_the_Run-Time_Library_RTL:
1015 Search Paths and the Run-Time Library (RTL)
1016 -------------------------------------------
1018 With the GNAT source-based library system, the compiler must be able to
1019 find source files for units that are needed by the unit being compiled.
1020 Search paths are used to guide this process.
1022 The compiler compiles one source file whose name must be given
1023 explicitly on the command line. In other words, no searching is done
1024 for this file. To find all other source files that are needed (the most
1025 common being the specs of units), the compiler examines the following
1026 directories, in the following order:
1028 * The directory containing the source file of the main unit being compiled
1029 (the file name on the command line).
1031 * Each directory named by an *-I* switch given on the *gcc*
1032 command line, in the order given.
1034 .. index:: ADA_PRJ_INCLUDE_FILE
1036 * Each of the directories listed in the text file whose name is given
1037 by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable.
1038 :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat
1039 driver when project files are used. It should not normally be set
1042 .. index:: ADA_INCLUDE_PATH
1044 * Each of the directories listed in the value of the
1045 :envvar:`ADA_INCLUDE_PATH` environment variable.
1046 Construct this value
1047 exactly as the :envvar:`PATH` environment variable: a list of directory
1048 names separated by colons (semicolons when working with the NT version).
1050 * The content of the :file:`ada_source_path` file which is part of the GNAT
1051 installation tree and is used to store standard libraries such as the
1052 GNAT Run Time Library (RTL) source files.
1053 :ref:`Installing_a_library`
1055 Specifying the switch *-I-*
1056 inhibits the use of the directory
1057 containing the source file named in the command line. You can still
1058 have this directory on your search path, but in this case it must be
1059 explicitly requested with a *-I* switch.
1061 Specifying the switch *-nostdinc*
1062 inhibits the search of the default location for the GNAT Run Time
1063 Library (RTL) source files.
1065 The compiler outputs its object files and ALI files in the current
1067 Caution: The object file can be redirected with the *-o* switch;
1068 however, *gcc* and `gnat1` have not been coordinated on this
1069 so the :file:`ALI` file will not go to the right place. Therefore, you should
1070 avoid using the *-o* switch.
1072 .. index:: System.IO
1074 The packages `Ada`, `System`, and `Interfaces` and their
1075 children make up the GNAT RTL, together with the simple `System.IO`
1076 package used in the `"Hello World"` example. The sources for these units
1077 are needed by the compiler and are kept together in one directory. Not
1078 all of the bodies are needed, but all of the sources are kept together
1079 anyway. In a normal installation, you need not specify these directory
1080 names when compiling or binding. Either the environment variables or
1081 the built-in defaults cause these files to be found.
1083 In addition to the language-defined hierarchies (`System`, `Ada` and
1084 `Interfaces`), the GNAT distribution provides a fourth hierarchy,
1085 consisting of child units of `GNAT`. This is a collection of generally
1086 useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual`
1087 for further details.
1089 Besides simplifying access to the RTL, a major use of search paths is
1090 in compiling sources from multiple directories. This can make
1091 development environments much more flexible.
1093 .. _Order_of_Compilation_Issues:
1095 Order of Compilation Issues
1096 ---------------------------
1098 If, in our earlier example, there was a spec for the `hello`
1099 procedure, it would be contained in the file :file:`hello.ads`; yet this
1100 file would not have to be explicitly compiled. This is the result of the
1101 model we chose to implement library management. Some of the consequences
1102 of this model are as follows:
1104 * There is no point in compiling specs (except for package
1105 specs with no bodies) because these are compiled as needed by clients. If
1106 you attempt a useless compilation, you will receive an error message.
1107 It is also useless to compile subunits because they are compiled as needed
1110 * There are no order of compilation requirements: performing a
1111 compilation never obsoletes anything. The only way you can obsolete
1112 something and require recompilations is to modify one of the
1113 source files on which it depends.
1115 * There is no library as such, apart from the ALI files
1116 (:ref:`The_Ada_Library_Information_Files`, for information on the format
1117 of these files). For now we find it convenient to create separate ALI files,
1118 but eventually the information therein may be incorporated into the object
1121 * When you compile a unit, the source files for the specs of all units
1122 that it |withs|, all its subunits, and the bodies of any generics it
1123 instantiates must be available (reachable by the search-paths mechanism
1124 described above), or you will receive a fatal error message.
1131 The following are some typical Ada compilation command line examples:
1137 Compile body in file :file:`xyz.adb` with all default options.
1141 $ gcc -c -O2 -gnata xyz-def.adb
1143 Compile the child unit package in file :file:`xyz-def.adb` with extensive
1144 optimizations, and pragma `Assert`/`Debug` statements
1149 $ gcc -c -gnatc abc-def.adb
1151 Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only
1155 .. _Switches_for_gcc:
1160 The *gcc* command accepts switches that control the
1161 compilation process. These switches are fully described in this section:
1162 first an alphabetical listing of all switches with a brief description,
1163 and then functionally grouped sets of switches with more detailed
1166 More switches exist for GCC than those documented here, especially
1167 for specific targets. However, their use is not recommended as
1168 they may change code generation in ways that are incompatible with
1169 the Ada run-time library, or can cause inconsistencies between
1172 .. _Alphabetical_List_of_All_Switches:
1174 Alphabetical List of All Switches
1175 ---------------------------------
1180 Compile your program to run on `target`, which is the name of a
1181 system configuration. You must have a GNAT cross-compiler built if
1182 `target` is not the same as your host system.
1188 Load compiler executables (for example, `gnat1`, the Ada compiler)
1189 from `dir` instead of the default location. Only use this switch
1190 when multiple versions of the GNAT compiler are available.
1191 See the "Options for Directory Search" section in the
1192 :title:`Using the GNU Compiler Collection (GCC)` manual for further details.
1193 You would normally use the *-b* or *-V* switch instead.
1198 Compile. Always use this switch when compiling Ada programs.
1200 Note: for some other languages when using *gcc*, notably in
1201 the case of C and C++, it is possible to use
1202 use *gcc* without a *-c* switch to
1203 compile and link in one step. In the case of GNAT, you
1204 cannot use this approach, because the binder must be run
1205 and *gcc* cannot be used to run the GNAT binder.
1208 .. index:: -fcallgraph-info (gcc)
1210 :samp:`-fcallgraph-info[=su,da]`
1211 Makes the compiler output callgraph information for the program, on a
1212 per-file basis. The information is generated in the VCG format. It can
1213 be decorated with additional, per-node and/or per-edge information, if a
1214 list of comma-separated markers is additionally specified. When the
1215 `su` marker is specified, the callgraph is decorated with stack usage
1216 information; it is equivalent to *-fstack-usage*. When the `da`
1217 marker is specified, the callgraph is decorated with information about
1218 dynamically allocated objects.
1221 .. index:: -fdump-scos (gcc)
1224 Generates SCO (Source Coverage Obligation) information in the ALI file.
1225 This information is used by advanced coverage tools. See unit :file:`SCOs`
1226 in the compiler sources for details in files :file:`scos.ads` and
1230 .. index:: -fdump-xref (gcc)
1233 Generates cross reference information in GLI files for C and C++ sources.
1234 The GLI files have the same syntax as the ALI files for Ada, and can be used
1235 for source navigation in IDEs and on the command line using e.g. gnatxref
1236 and the *--ext=gli* switch.
1239 .. index:: -flto (gcc)
1242 Enables Link Time Optimization. This switch must be used in conjunction
1243 with the traditional *-Ox* switches and instructs the compiler to
1244 defer most optimizations until the link stage. The advantage of this
1245 approach is that the compiler can do a whole-program analysis and choose
1246 the best interprocedural optimization strategy based on a complete view
1247 of the program, instead of a fragmentary view with the usual approach.
1248 This can also speed up the compilation of big programs and reduce the
1249 size of the executable, compared with a traditional per-unit compilation
1250 with inlining across modules enabled by the *-gnatn* switch.
1251 The drawback of this approach is that it may require more memory and that
1252 the debugging information generated by -g with it might be hardly usable.
1253 The switch, as well as the accompanying *-Ox* switches, must be
1254 specified both for the compilation and the link phases.
1255 If the `n` parameter is specified, the optimization and final code
1256 generation at link time are executed using `n` parallel jobs by
1257 means of an installed *make* program.
1260 .. index:: -fno-inline (gcc)
1263 Suppresses all inlining, unless requested with pragma `Inline_Always`. The
1264 effect is enforced regardless of other optimization or inlining switches.
1265 Note that inlining can also be suppressed on a finer-grained basis with
1269 .. index:: -fno-inline-functions (gcc)
1271 :samp:`-fno-inline-functions`
1272 Suppresses automatic inlining of subprograms, which is enabled
1276 .. index:: -fno-inline-small-functions (gcc)
1278 :samp:`-fno-inline-small-functions`
1279 Suppresses automatic inlining of small subprograms, which is enabled
1283 .. index:: -fno-inline-functions-called-once (gcc)
1285 :samp:`-fno-inline-functions-called-once`
1286 Suppresses inlining of subprograms local to the unit and called once
1287 from within it, which is enabled if *-O1* is used.
1290 .. index:: -fno-ivopts (gcc)
1293 Suppresses high-level loop induction variable optimizations, which are
1294 enabled if *-O1* is used. These optimizations are generally
1295 profitable but, for some specific cases of loops with numerous uses
1296 of the iteration variable that follow a common pattern, they may end
1297 up destroying the regularity that could be exploited at a lower level
1298 and thus producing inferior code.
1301 .. index:: -fno-strict-aliasing (gcc)
1303 :samp:`-fno-strict-aliasing`
1304 Causes the compiler to avoid assumptions regarding non-aliasing
1305 of objects of different types. See
1306 :ref:`Optimization_and_Strict_Aliasing` for details.
1309 .. index:: -fno-strict-overflow (gcc)
1311 :samp:`-fno-strict-overflow`
1312 Causes the compiler to avoid assumptions regarding the rules of signed
1313 integer overflow. These rules specify that signed integer overflow will
1314 result in a Constraint_Error exception at run time and are enforced in
1315 default mode by the compiler, so this switch should not be necessary in
1316 normal operating mode. It might be useful in conjunction with *-gnato0*
1317 for very peculiar cases of low-level programming.
1320 .. index:: -fstack-check (gcc)
1322 :samp:`-fstack-check`
1323 Activates stack checking.
1324 See :ref:`Stack_Overflow_Checking` for details.
1327 .. index:: -fstack-usage (gcc)
1329 :samp:`-fstack-usage`
1330 Makes the compiler output stack usage information for the program, on a
1331 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
1337 Generate debugging information. This information is stored in the object
1338 file and copied from there to the final executable file by the linker,
1339 where it can be read by the debugger. You must use the
1340 *-g* switch if you plan on using the debugger.
1343 .. index:: -gnat05 (gcc)
1346 Allow full Ada 2005 features.
1349 .. index:: -gnat12 (gcc)
1352 Allow full Ada 2012 features.
1354 .. index:: -gnat83 (gcc)
1356 .. index:: -gnat2005 (gcc)
1359 Allow full Ada 2005 features (same as *-gnat05*)
1362 .. index:: -gnat2012 (gcc)
1365 Allow full Ada 2012 features (same as *-gnat12*)
1369 Enforce Ada 83 restrictions.
1372 .. index:: -gnat95 (gcc)
1375 Enforce Ada 95 restrictions.
1377 Note: for compatibility with some Ada 95 compilers which support only
1378 the `overriding` keyword of Ada 2005, the *-gnatd.D* switch can
1379 be used along with *-gnat95* to achieve a similar effect with GNAT.
1381 *-gnatd.D* instructs GNAT to consider `overriding` as a keyword
1382 and handle its associated semantic checks, even in Ada 95 mode.
1385 .. index:: -gnata (gcc)
1388 Assertions enabled. `Pragma Assert` and `pragma Debug` to be
1389 activated. Note that these pragmas can also be controlled using the
1390 configuration pragmas `Assertion_Policy` and `Debug_Policy`.
1391 It also activates pragmas `Check`, `Precondition`, and
1392 `Postcondition`. Note that these pragmas can also be controlled
1393 using the configuration pragma `Check_Policy`. In Ada 2012, it
1394 also activates all assertions defined in the RM as aspects: preconditions,
1395 postconditions, type invariants and (sub)type predicates. In all Ada modes,
1396 corresponding pragmas for type invariants and (sub)type predicates are
1397 also activated. The default is that all these assertions are disabled,
1398 and have no effect, other than being checked for syntactic validity, and
1399 in the case of subtype predicates, constructions such as membership tests
1400 still test predicates even if assertions are turned off.
1403 .. index:: -gnatA (gcc)
1406 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
1410 .. index:: -gnatb (gcc)
1413 Generate brief messages to :file:`stderr` even if verbose mode set.
1416 .. index:: -gnatB (gcc)
1419 Assume no invalid (bad) values except for 'Valid attribute use
1420 (:ref:`Validity_Checking`).
1423 .. index:: -gnatc (gcc)
1426 Check syntax and semantics only (no code generation attempted). When the
1427 compiler is invoked by *gnatmake*, if the switch *-gnatc* is
1428 only given to the compiler (after *-cargs* or in package Compiler of
1429 the project file, *gnatmake* will fail because it will not find the
1430 object file after compilation. If *gnatmake* is called with
1431 *-gnatc* as a builder switch (before *-cargs* or in package
1432 Builder of the project file) then *gnatmake* will not fail because
1433 it will not look for the object files after compilation, and it will not try
1434 to build and link. This switch may not be given if a previous `-gnatR`
1435 switch has been given, since `-gnatR` requires that the code generator
1436 be called to complete determination of representation information.
1439 .. index:: -gnatC (gcc)
1442 Generate CodePeer intermediate format (no code generation attempted).
1443 This switch will generate an intermediate representation suitable for
1444 use by CodePeer (:file:`.scil` files). This switch is not compatible with
1445 code generation (it will, among other things, disable some switches such
1446 as -gnatn, and enable others such as -gnata).
1449 .. index:: -gnatd (gcc)
1452 Specify debug options for the compiler. The string of characters after
1453 the *-gnatd* specify the specific debug options. The possible
1454 characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
1455 compiler source file :file:`debug.adb` for details of the implemented
1456 debug options. Certain debug options are relevant to applications
1457 programmers, and these are documented at appropriate points in this
1461 .. index:: -gnatD[nn] (gcc)
1464 Create expanded source files for source level debugging. This switch
1465 also suppress generation of cross-reference information
1466 (see *-gnatx*). Note that this switch is not allowed if a previous
1467 -gnatR switch has been given, since these two switches are not compatible.
1470 .. index:: -gnateA (gcc)
1473 Check that the actual parameters of a subprogram call are not aliases of one
1474 another. To qualify as aliasing, the actuals must denote objects of a composite
1475 type, their memory locations must be identical or overlapping, and at least one
1476 of the corresponding formal parameters must be of mode OUT or IN OUT.
1481 type Rec_Typ is record
1482 Data : Integer := 0;
1485 function Self (Val : Rec_Typ) return Rec_Typ is
1490 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
1493 end Detect_Aliasing;
1497 Detect_Aliasing (Obj, Obj);
1498 Detect_Aliasing (Obj, Self (Obj));
1501 In the example above, the first call to `Detect_Aliasing` fails with a
1502 `Program_Error` at runtime because the actuals for `Val_1` and
1503 `Val_2` denote the same object. The second call executes without raising
1504 an exception because `Self(Obj)` produces an anonymous object which does
1505 not share the memory location of `Obj`.
1508 .. index:: -gnatec (gcc)
1510 :samp:`-gnatec={path}`
1511 Specify a configuration pragma file
1512 (the equal sign is optional)
1513 (:ref:`The_Configuration_Pragmas_Files`).
1516 .. index:: -gnateC (gcc)
1519 Generate CodePeer messages in a compiler-like format. This switch is only
1520 effective if *-gnatcC* is also specified and requires an installation
1524 .. index:: -gnated (gcc)
1527 Disable atomic synchronization
1530 .. index:: -gnateD (gcc)
1532 :samp:`-gnateDsymbol[={value}]`
1533 Defines a symbol, associated with `value`, for preprocessing.
1534 (:ref:`Integrated_Preprocessing`).
1537 .. index:: -gnateE (gcc)
1540 Generate extra information in exception messages. In particular, display
1541 extra column information and the value and range associated with index and
1542 range check failures, and extra column information for access checks.
1543 In cases where the compiler is able to determine at compile time that
1544 a check will fail, it gives a warning, and the extra information is not
1545 produced at run time.
1548 .. index:: -gnatef (gcc)
1551 Display full source path name in brief error messages.
1554 .. index:: -gnateF (gcc)
1557 Check for overflow on all floating-point operations, including those
1558 for unconstrained predefined types. See description of pragma
1559 `Check_Float_Overflow` in GNAT RM.
1562 .. index:: -gnateg (gcc)
1567 The `-gnatc` switch must always be specified before this switch, e.g.
1568 `-gnatceg`. Generate a C header from the Ada input file. See
1569 :ref:`Generating_C_Headers_for_Ada_Specifications` for more
1573 .. index:: -gnateG (gcc)
1576 Save result of preprocessing in a text file.
1579 .. index:: -gnatei (gcc)
1581 :samp:`-gnatei{nnn}`
1582 Set maximum number of instantiations during compilation of a single unit to
1583 `nnn`. This may be useful in increasing the default maximum of 8000 for
1584 the rare case when a single unit legitimately exceeds this limit.
1587 .. index:: -gnateI (gcc)
1589 :samp:`-gnateI{nnn}`
1590 Indicates that the source is a multi-unit source and that the index of the
1591 unit to compile is `nnn`. `nnn` needs to be a positive number and need
1592 to be a valid index in the multi-unit source.
1595 .. index:: -gnatel (gcc)
1598 This switch can be used with the static elaboration model to issue info
1600 where implicit `pragma Elaborate` and `pragma Elaborate_All`
1601 are generated. This is useful in diagnosing elaboration circularities
1602 caused by these implicit pragmas when using the static elaboration
1603 model. See See the section in this guide on elaboration checking for
1604 further details. These messages are not generated by default, and are
1605 intended only for temporary use when debugging circularity problems.
1608 .. index:: -gnatel (gcc)
1611 This switch turns off the info messages about implicit elaboration pragmas.
1614 .. index:: -gnatem (gcc)
1616 :samp:`-gnatem={path}`
1617 Specify a mapping file
1618 (the equal sign is optional)
1619 (:ref:`Units_to_Sources_Mapping_Files`).
1622 .. index:: -gnatep (gcc)
1624 :samp:`-gnatep={file}`
1625 Specify a preprocessing data file
1626 (the equal sign is optional)
1627 (:ref:`Integrated_Preprocessing`).
1630 .. index:: -gnateP (gcc)
1633 Turn categorization dependency errors into warnings.
1634 Ada requires that units that WITH one another have compatible categories, for
1635 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
1636 these errors become warnings (which can be ignored, or suppressed in the usual
1637 manner). This can be useful in some specialized circumstances such as the
1638 temporary use of special test software.
1641 .. index:: -gnateS (gcc)
1644 Synonym of *-fdump-scos*, kept for backwards compatibility.
1647 .. index:: -gnatet=file (gcc)
1649 :samp:`-gnatet={path}`
1650 Generate target dependent information. The format of the output file is
1651 described in the section about switch *-gnateT*.
1654 .. index:: -gnateT (gcc)
1656 :samp:`-gnateT={path}`
1657 Read target dependent information, such as endianness or sizes and alignments
1658 of base type. If this switch is passed, the default target dependent
1659 information of the compiler is replaced by the one read from the input file.
1660 This is used by tools other than the compiler, e.g. to do
1661 semantic analysis of programs that will run on some other target than
1662 the machine on which the tool is run.
1664 The following target dependent values should be defined,
1665 where `Nat` denotes a natural integer value, `Pos` denotes a
1666 positive integer value, and fields marked with a question mark are
1667 boolean fields, where a value of 0 is False, and a value of 1 is True:
1672 Bits_BE : Nat; -- Bits stored big-endian?
1673 Bits_Per_Unit : Pos; -- Bits in a storage unit
1674 Bits_Per_Word : Pos; -- Bits in a word
1675 Bytes_BE : Nat; -- Bytes stored big-endian?
1676 Char_Size : Pos; -- Standard.Character'Size
1677 Double_Float_Alignment : Nat; -- Alignment of double float
1678 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
1679 Double_Size : Pos; -- Standard.Long_Float'Size
1680 Float_Size : Pos; -- Standard.Float'Size
1681 Float_Words_BE : Nat; -- Float words stored big-endian?
1682 Int_Size : Pos; -- Standard.Integer'Size
1683 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
1684 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
1685 Long_Size : Pos; -- Standard.Long_Integer'Size
1686 Maximum_Alignment : Pos; -- Maximum permitted alignment
1687 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
1688 Pointer_Size : Pos; -- System.Address'Size
1689 Short_Enums : Nat; -- Short foreign convention enums?
1690 Short_Size : Pos; -- Standard.Short_Integer'Size
1691 Strict_Alignment : Nat; -- Strict alignment?
1692 System_Allocator_Alignment : Nat; -- Alignment for malloc calls
1693 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
1694 Words_BE : Nat; -- Words stored big-endian?
1697 The format of the input file is as follows. First come the values of
1698 the variables defined above, with one line per value:
1705 where `name` is the name of the parameter, spelled out in full,
1706 and cased as in the above list, and `value` is an unsigned decimal
1707 integer. Two or more blanks separates the name from the value.
1709 All the variables must be present, in alphabetical order (i.e. the
1710 same order as the list above).
1712 Then there is a blank line to separate the two parts of the file. Then
1713 come the lines showing the floating-point types to be registered, with
1714 one line per registered mode:
1719 name digs float_rep size alignment
1722 where `name` is the string name of the type (which can have
1723 single spaces embedded in the name (e.g. long double), `digs` is
1724 the number of digits for the floating-point type, `float_rep` is
1725 the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
1726 AAMP), `size` is the size in bits, `alignment` is the
1727 alignment in bits. The name is followed by at least two blanks, fields
1728 are separated by at least one blank, and a LF character immediately
1729 follows the alignment field.
1731 Here is an example of a target parameterization file:
1741 Double_Float_Alignment 0
1742 Double_Scalar_Alignment 0
1747 Long_Double_Size 128
1750 Maximum_Alignment 16
1751 Max_Unaligned_Field 64
1755 System_Allocator_Alignment 16
1761 long double 18 I 80 128
1766 .. index:: -gnateu (gcc)
1769 Ignore unrecognized validity, warning, and style switches that
1770 appear after this switch is given. This may be useful when
1771 compiling sources developed on a later version of the compiler
1772 with an earlier version. Of course the earlier version must
1773 support this switch.
1776 .. index:: -gnateV (gcc)
1779 Check that all actual parameters of a subprogram call are valid according to
1780 the rules of validity checking (:ref:`Validity_Checking`).
1783 .. index:: -gnateY (gcc)
1786 Ignore all STYLE_CHECKS pragmas. Full legality checks
1787 are still carried out, but the pragmas have no effect
1788 on what style checks are active. This allows all style
1789 checking options to be controlled from the command line.
1792 .. index:: -gnatE (gcc)
1795 Full dynamic elaboration checks.
1798 .. index:: -gnatf (gcc)
1801 Full errors. Multiple errors per line, all undefined references, do not
1802 attempt to suppress cascaded errors.
1805 .. index:: -gnatF (gcc)
1808 Externals names are folded to all uppercase.
1811 .. index:: -gnatg (gcc)
1814 Internal GNAT implementation mode. This should not be used for
1815 applications programs, it is intended only for use by the compiler
1816 and its run-time library. For documentation, see the GNAT sources.
1817 Note that *-gnatg* implies
1820 so that all standard warnings and all standard style options are turned on.
1821 All warnings and style messages are treated as errors.
1824 .. index:: -gnatG[nn] (gcc)
1827 List generated expanded code in source form.
1830 .. index:: -gnath (gcc)
1833 Output usage information. The output is written to :file:`stdout`.
1836 .. index:: -gnati (gcc)
1839 Identifier character set (`c` = 1/2/3/4/8/9/p/f/n/w).
1840 For details of the possible selections for `c`,
1841 see :ref:`Character_Set_Control`.
1844 .. index:: -gnatI (gcc)
1847 Ignore representation clauses. When this switch is used,
1848 representation clauses are treated as comments. This is useful
1849 when initially porting code where you want to ignore rep clause
1850 problems, and also for compiling foreign code (particularly
1851 for use with ASIS). The representation clauses that are ignored
1852 are: enumeration_representation_clause, record_representation_clause,
1853 and attribute_definition_clause for the following attributes:
1854 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1855 Object_Size, Size, Small, Stream_Size, and Value_Size.
1856 Note that this option should be used only for compiling -- the
1857 code is likely to malfunction at run time.
1859 Note that when `-gnatct` is used to generate trees for input
1860 into `ASIS` tools, these representation clauses are removed
1861 from the tree and ignored. This means that the tool will not see them.
1864 .. index:: -gnatjnn (gcc)
1867 Reformat error messages to fit on `nn` character lines
1870 .. index:: -gnatk (gcc)
1873 Limit file names to `n` (1-999) characters (`k` = krunch).
1876 .. index:: -gnatl (gcc)
1879 Output full source listing with embedded error messages.
1882 .. index:: -gnatL (gcc)
1885 Used in conjunction with -gnatG or -gnatD to intersperse original
1886 source lines (as comment lines with line numbers) in the expanded
1890 .. index:: -gnatm (gcc)
1893 Limit number of detected error or warning messages to `n`
1894 where `n` is in the range 1..999999. The default setting if
1895 no switch is given is 9999. If the number of warnings reaches this
1896 limit, then a message is output and further warnings are suppressed,
1897 but the compilation is continued. If the number of error messages
1898 reaches this limit, then a message is output and the compilation
1899 is abandoned. The equal sign here is optional. A value of zero
1900 means that no limit applies.
1903 .. index:: -gnatn (gcc)
1906 Activate inlining for subprograms for which pragma `Inline` is
1907 specified. This inlining is performed by the GCC back-end. An optional
1908 digit sets the inlining level: 1 for moderate inlining across modules
1909 or 2 for full inlining across modules. If no inlining level is specified,
1910 the compiler will pick it based on the optimization level.
1913 .. index:: -gnatN (gcc)
1916 Activate front end inlining for subprograms for which
1917 pragma `Inline` is specified. This inlining is performed
1918 by the front end and will be visible in the
1921 When using a gcc-based back end (in practice this means using any version
1922 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
1923 *-gnatN* is deprecated, and the use of *-gnatn* is preferred.
1924 Historically front end inlining was more extensive than the gcc back end
1925 inlining, but that is no longer the case.
1928 .. index:: -gnato0 (gcc)
1931 Suppresses overflow checking. This causes the behavior of the compiler to
1932 match the default for older versions where overflow checking was suppressed
1933 by default. This is equivalent to having
1934 `pragma Suppress (Overflow_Mode)` in a configuration pragma file.
1937 .. index:: -gnato?? (gcc)
1940 Set default mode for handling generation of code to avoid intermediate
1941 arithmetic overflow. Here `??` is two digits, a
1942 single digit, or nothing. Each digit is one of the digits `1`
1945 ===== ===============================================================
1946 Digit Interpretation
1947 ----- ---------------------------------------------------------------
1948 *1* All intermediate overflows checked against base type (`STRICT`)
1949 *2* Minimize intermediate overflows (`MINIMIZED`)
1950 *3* Eliminate intermediate overflows (`ELIMINATED`)
1951 ===== ===============================================================
1953 If only one digit appears, then it applies to all
1954 cases; if two digits are given, then the first applies outside
1955 assertions, pre/postconditions, and type invariants, and the second
1956 applies within assertions, pre/postconditions, and type invariants.
1958 If no digits follow the *-gnato*, then it is equivalent to
1960 causing all intermediate overflows to be handled in strict
1963 This switch also causes arithmetic overflow checking to be performed
1964 (as though `pragma Unsuppress (Overflow_Mode)` had been specified).
1966 The default if no option *-gnato* is given is that overflow handling
1967 is in `STRICT` mode (computations done using the base type), and that
1968 overflow checking is enabled.
1970 Note that division by zero is a separate check that is not
1971 controlled by this switch (divide-by-zero checking is on by default).
1973 See also :ref:`Specifying_the_Desired_Mode`.
1976 .. index:: -gnatp (gcc)
1979 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
1980 has no effect if cancelled by a subsequent *-gnat-p* switch.
1983 .. index:: -gnat-p (gcc)
1986 Cancel effect of previous *-gnatp* switch.
1989 .. index:: -gnatP (gcc)
1992 Enable polling. This is required on some systems (notably Windows NT) to
1993 obtain asynchronous abort and asynchronous transfer of control capability.
1994 See `Pragma_Polling` in the :title:`GNAT_Reference_Manual` for full
1998 .. index:: -gnatq (gcc)
2001 Don't quit. Try semantics, even if parse errors.
2004 .. index:: -gnatQ (gcc)
2007 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2008 Note that code generation is still suppressed in the presence of any
2009 errors, so even with *-gnatQ* no object file is generated.
2012 .. index:: -gnatr (gcc)
2015 Treat pragma Restrictions as Restriction_Warnings.
2018 .. index:: -gnatR (gcc)
2020 :samp:`-gnatR[0/1/2/3[s]]`
2021 Output representation information for declared types and objects.
2022 Note that this switch is not allowed if a previous `-gnatD` switch has
2023 been given, since these two switches are not compatible.
2027 Output convention and parameter passing mechanisms for all subprograms.
2030 .. index:: -gnats (gcc)
2036 .. index:: -gnatS (gcc)
2039 Print package Standard.
2042 .. index:: -gnatt (gcc)
2045 Generate tree output file.
2048 .. index:: -gnatT (gcc)
2051 All compiler tables start at `nnn` times usual starting size.
2054 .. index:: -gnatu (gcc)
2057 List units for this compilation.
2060 .. index:: -gnatU (gcc)
2063 Tag all error messages with the unique string 'error:'
2066 .. index:: -gnatv (gcc)
2069 Verbose mode. Full error output with source lines to :file:`stdout`.
2072 .. index:: -gnatV (gcc)
2075 Control level of validity checking (:ref:`Validity_Checking`).
2078 .. index:: -gnatw (gcc)
2082 `xxx` is a string of option letters that denotes
2083 the exact warnings that
2084 are enabled or disabled (:ref:`Warning_Message_Control`).
2087 .. index:: -gnatW (gcc)
2090 Wide character encoding method
2091 (`e`\ =n/h/u/s/e/8).
2094 .. index:: -gnatx (gcc)
2097 Suppress generation of cross-reference information.
2100 .. index:: -gnatX (gcc)
2103 Enable GNAT implementation extensions and latest Ada version.
2106 .. index:: -gnaty (gcc)
2109 Enable built-in style checks (:ref:`Style_Checking`).
2112 .. index:: -gnatz (gcc)
2115 Distribution stub generation and compilation
2116 (`m`\ =r/c for receiver/caller stubs).
2124 Direct GNAT to search the `dir` directory for source files needed by
2125 the current compilation
2126 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2129 .. index:: -I- (gcc)
2134 Except for the source file named in the command line, do not look for source
2135 files in the directory containing the source file named in the command line
2136 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2142 This switch is used in *gcc* to redirect the generated object file
2143 and its associated ALI file. Beware of this switch with GNAT, because it may
2144 cause the object file and ALI file to have different names which in turn
2145 may confuse the binder and the linker.
2148 .. index:: -nostdinc (gcc)
2151 Inhibit the search of the default location for the GNAT Run Time
2152 Library (RTL) source files.
2155 .. index:: -nostdlib (gcc)
2158 Inhibit the search of the default location for the GNAT Run Time
2159 Library (RTL) ALI files.
2165 `n` controls the optimization level:
2167 ======= ==================================================================
2169 ------- ------------------------------------------------------------------
2170 *0* No optimization, the default setting if no *-O* appears
2171 *1* Normal optimization, the default if you specify *-O* without an
2172 operand. A good compromise between code quality and compilation
2174 *2* Extensive optimization, may improve execution time, possibly at
2175 the cost of substantially increased compilation time.
2176 *3* Same as *-O2*, and also includes inline expansion for small
2177 subprograms in the same unit.
2178 *s* Optimize space usage
2179 ======= ==================================================================
2181 See also :ref:`Optimization_Levels`.
2184 .. index:: -pass-exit-codes (gcc)
2186 :samp:`-pass-exit-codes`
2187 Catch exit codes from the compiler and use the most meaningful as
2191 .. index:: --RTS (gcc)
2193 :samp:`--RTS={rts-path}`
2194 Specifies the default location of the runtime library. Same meaning as the
2195 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
2201 Used in place of *-c* to
2202 cause the assembler source file to be
2203 generated, using :file:`.s` as the extension,
2204 instead of the object file.
2205 This may be useful if you need to examine the generated assembly code.
2208 .. index:: -fverbose-asm (gcc)
2210 :samp:`-fverbose-asm`
2211 Used in conjunction with *-S*
2212 to cause the generated assembly code file to be annotated with variable
2213 names, making it significantly easier to follow.
2219 Show commands generated by the *gcc* driver. Normally used only for
2220 debugging purposes or if you need to be sure what version of the
2221 compiler you are executing.
2227 Execute `ver` version of the compiler. This is the *gcc*
2228 version, not the GNAT version.
2234 Turn off warnings generated by the back end of the compiler. Use of
2235 this switch also causes the default for front end warnings to be set
2236 to suppress (as though *-gnatws* had appeared at the start of
2240 .. index:: Combining GNAT switches
2242 You may combine a sequence of GNAT switches into a single switch. For
2243 example, the combined switch
2249 is equivalent to specifying the following sequence of switches:
2253 -gnato -gnatf -gnati3
2255 The following restrictions apply to the combination of switches
2258 * The switch *-gnatc* if combined with other switches must come
2259 first in the string.
2261 * The switch *-gnats* if combined with other switches must come
2262 first in the string.
2265 *-gnatzc* and *-gnatzr* may not be combined with any other
2266 switches, and only one of them may appear in the command line.
2268 * The switch *-gnat-p* may not be combined with any other switch.
2270 * Once a 'y' appears in the string (that is a use of the *-gnaty*
2271 switch), then all further characters in the switch are interpreted
2272 as style modifiers (see description of *-gnaty*).
2274 * Once a 'd' appears in the string (that is a use of the *-gnatd*
2275 switch), then all further characters in the switch are interpreted
2276 as debug flags (see description of *-gnatd*).
2278 * Once a 'w' appears in the string (that is a use of the *-gnatw*
2279 switch), then all further characters in the switch are interpreted
2280 as warning mode modifiers (see description of *-gnatw*).
2282 * Once a 'V' appears in the string (that is a use of the *-gnatV*
2283 switch), then all further characters in the switch are interpreted
2284 as validity checking options (:ref:`Validity_Checking`).
2286 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2287 a combined list of options.
2289 .. _Output_and_Error_Message_Control:
2291 Output and Error Message Control
2292 --------------------------------
2296 The standard default format for error messages is called 'brief format'.
2297 Brief format messages are written to :file:`stderr` (the standard error
2298 file) and have the following form:
2302 e.adb:3:04: Incorrect spelling of keyword "function"
2303 e.adb:4:20: ";" should be "is"
2305 The first integer after the file name is the line number in the file,
2306 and the second integer is the column number within the line.
2307 `GPS` can parse the error messages
2308 and point to the referenced character.
2309 The following switches provide control over the error message
2313 .. index:: -gnatv (gcc)
2316 The `v` stands for verbose.
2317 The effect of this setting is to write long-format error
2318 messages to :file:`stdout` (the standard output file.
2319 The same program compiled with the
2320 *-gnatv* switch would generate:
2324 3. funcion X (Q : Integer)
2326 >>> Incorrect spelling of keyword "function"
2329 >>> ";" should be "is"
2332 The vertical bar indicates the location of the error, and the :samp:`>>>`
2333 prefix can be used to search for error messages. When this switch is
2334 used the only source lines output are those with errors.
2337 .. index:: -gnatl (gcc)
2340 The `l` stands for list.
2341 This switch causes a full listing of
2342 the file to be generated. In the case where a body is
2343 compiled, the corresponding spec is also listed, along
2344 with any subunits. Typical output from compiling a package
2345 body :file:`p.adb` might look like::
2349 1. package body p is
2351 3. procedure a is separate;
2362 2. pragma Elaborate_Body
2383 When you specify the *-gnatv* or *-gnatl* switches and
2384 standard output is redirected, a brief summary is written to
2385 :file:`stderr` (standard error) giving the number of error messages and
2386 warning messages generated.
2389 .. index:: -gnatl=fname (gcc)
2391 :samp:`-gnatl={fname}`
2392 This has the same effect as *-gnatl* except that the output is
2393 written to a file instead of to standard output. If the given name
2394 :file:`fname` does not start with a period, then it is the full name
2395 of the file to be written. If :file:`fname` is an extension, it is
2396 appended to the name of the file being compiled. For example, if
2397 file :file:`xyz.adb` is compiled with *-gnatl=.lst*,
2398 then the output is written to file xyz.adb.lst.
2401 .. index:: -gnatU (gcc)
2404 This switch forces all error messages to be preceded by the unique
2405 string 'error:'. This means that error messages take a few more
2406 characters in space, but allows easy searching for and identification
2410 .. index:: -gnatb (gcc)
2413 The `b` stands for brief.
2414 This switch causes GNAT to generate the
2415 brief format error messages to :file:`stderr` (the standard error
2416 file) as well as the verbose
2417 format message or full listing (which as usual is written to
2418 :file:`stdout` (the standard output file).
2421 .. index:: -gnatm (gcc)
2424 The `m` stands for maximum.
2425 `n` is a decimal integer in the
2426 range of 1 to 999999 and limits the number of error or warning
2427 messages to be generated. For example, using
2428 *-gnatm2* might yield
2432 e.adb:3:04: Incorrect spelling of keyword "function"
2433 e.adb:5:35: missing ".."
2434 fatal error: maximum number of errors detected
2435 compilation abandoned
2438 The default setting if
2439 no switch is given is 9999. If the number of warnings reaches this
2440 limit, then a message is output and further warnings are suppressed,
2441 but the compilation is continued. If the number of error messages
2442 reaches this limit, then a message is output and the compilation
2443 is abandoned. A value of zero means that no limit applies.
2445 Note that the equal sign is optional, so the switches
2446 *-gnatm2* and *-gnatm=2* are equivalent.
2449 .. index:: -gnatf (gcc)
2452 .. index:: Error messages, suppressing
2454 The `f` stands for full.
2455 Normally, the compiler suppresses error messages that are likely to be
2456 redundant. This switch causes all error
2457 messages to be generated. In particular, in the case of
2458 references to undefined variables. If a given variable is referenced
2459 several times, the normal format of messages is
2463 e.adb:7:07: "V" is undefined (more references follow)
2465 where the parenthetical comment warns that there are additional
2466 references to the variable `V`. Compiling the same program with the
2467 *-gnatf* switch yields
2471 e.adb:7:07: "V" is undefined
2472 e.adb:8:07: "V" is undefined
2473 e.adb:8:12: "V" is undefined
2474 e.adb:8:16: "V" is undefined
2475 e.adb:9:07: "V" is undefined
2476 e.adb:9:12: "V" is undefined
2478 The *-gnatf* switch also generates additional information for
2479 some error messages. Some examples are:
2481 * Details on possibly non-portable unchecked conversion
2483 * List possible interpretations for ambiguous calls
2485 * Additional details on incorrect parameters
2488 .. index:: -gnatjnn (gcc)
2491 In normal operation mode (or if *-gnatj0* is used), then error messages
2492 with continuation lines are treated as though the continuation lines were
2493 separate messages (and so a warning with two continuation lines counts as
2494 three warnings, and is listed as three separate messages).
2496 If the *-gnatjnn* switch is used with a positive value for nn, then
2497 messages are output in a different manner. A message and all its continuation
2498 lines are treated as a unit, and count as only one warning or message in the
2499 statistics totals. Furthermore, the message is reformatted so that no line
2500 is longer than nn characters.
2503 .. index:: -gnatq (gcc)
2506 The `q` stands for quit (really 'don't quit').
2507 In normal operation mode, the compiler first parses the program and
2508 determines if there are any syntax errors. If there are, appropriate
2509 error messages are generated and compilation is immediately terminated.
2511 GNAT to continue with semantic analysis even if syntax errors have been
2512 found. This may enable the detection of more errors in a single run. On
2513 the other hand, the semantic analyzer is more likely to encounter some
2514 internal fatal error when given a syntactically invalid tree.
2517 .. index:: -gnatQ (gcc)
2520 In normal operation mode, the :file:`ALI` file is not generated if any
2521 illegalities are detected in the program. The use of *-gnatQ* forces
2522 generation of the :file:`ALI` file. This file is marked as being in
2523 error, so it cannot be used for binding purposes, but it does contain
2524 reasonably complete cross-reference information, and thus may be useful
2525 for use by tools (e.g., semantic browsing tools or integrated development
2526 environments) that are driven from the :file:`ALI` file. This switch
2527 implies *-gnatq*, since the semantic phase must be run to get a
2528 meaningful ALI file.
2530 In addition, if *-gnatt* is also specified, then the tree file is
2531 generated even if there are illegalities. It may be useful in this case
2532 to also specify *-gnatq* to ensure that full semantic processing
2533 occurs. The resulting tree file can be processed by ASIS, for the purpose
2534 of providing partial information about illegal units, but if the error
2535 causes the tree to be badly malformed, then ASIS may crash during the
2538 When *-gnatQ* is used and the generated :file:`ALI` file is marked as
2539 being in error, *gnatmake* will attempt to recompile the source when it
2540 finds such an :file:`ALI` file, including with switch *-gnatc*.
2542 Note that *-gnatQ* has no effect if *-gnats* is specified,
2543 since ALI files are never generated if *-gnats* is set.
2546 .. _Warning_Message_Control:
2548 Warning Message Control
2549 -----------------------
2551 .. index:: Warning messages
2553 In addition to error messages, which correspond to illegalities as defined
2554 in the Ada Reference Manual, the compiler detects two kinds of warning
2557 First, the compiler considers some constructs suspicious and generates a
2558 warning message to alert you to a possible error. Second, if the
2559 compiler detects a situation that is sure to raise an exception at
2560 run time, it generates a warning message. The following shows an example
2561 of warning messages:
2565 e.adb:4:24: warning: creation of object may raise Storage_Error
2566 e.adb:10:17: warning: static value out of range
2567 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2570 GNAT considers a large number of situations as appropriate
2571 for the generation of warning messages. As always, warnings are not
2572 definite indications of errors. For example, if you do an out-of-range
2573 assignment with the deliberate intention of raising a
2574 `Constraint_Error` exception, then the warning that may be
2575 issued does not indicate an error. Some of the situations for which GNAT
2576 issues warnings (at least some of the time) are given in the following
2577 list. This list is not complete, and new warnings are often added to
2578 subsequent versions of GNAT. The list is intended to give a general idea
2579 of the kinds of warnings that are generated.
2581 * Possible infinitely recursive calls
2583 * Out-of-range values being assigned
2585 * Possible order of elaboration problems
2587 * Size not a multiple of alignment for a record type
2589 * Assertions (pragma Assert) that are sure to fail
2593 * Address clauses with possibly unaligned values, or where an attempt is
2594 made to overlay a smaller variable with a larger one.
2596 * Fixed-point type declarations with a null range
2598 * Direct_IO or Sequential_IO instantiated with a type that has access values
2600 * Variables that are never assigned a value
2602 * Variables that are referenced before being initialized
2604 * Task entries with no corresponding `accept` statement
2606 * Duplicate accepts for the same task entry in a `select`
2608 * Objects that take too much storage
2610 * Unchecked conversion between types of differing sizes
2612 * Missing `return` statement along some execution path in a function
2614 * Incorrect (unrecognized) pragmas
2616 * Incorrect external names
2618 * Allocation from empty storage pool
2620 * Potentially blocking operation in protected type
2622 * Suspicious parenthesization of expressions
2624 * Mismatching bounds in an aggregate
2626 * Attempt to return local value by reference
2628 * Premature instantiation of a generic body
2630 * Attempt to pack aliased components
2632 * Out of bounds array subscripts
2634 * Wrong length on string assignment
2636 * Violations of style rules if style checking is enabled
2638 * Unused |with| clauses
2640 * `Bit_Order` usage that does not have any effect
2642 * `Standard.Duration` used to resolve universal fixed expression
2644 * Dereference of possibly null value
2646 * Declaration that is likely to cause storage error
2648 * Internal GNAT unit |withed| by application unit
2650 * Values known to be out of range at compile time
2652 * Unreferenced or unmodified variables. Note that a special
2653 exemption applies to variables which contain any of the substrings
2654 `DISCARD, DUMMY, IGNORE, JUNK, UNUSED`, in any casing. Such variables
2655 are considered likely to be intentionally used in a situation where
2656 otherwise a warning would be given, so warnings of this kind are
2657 always suppressed for such variables.
2659 * Address overlays that could clobber memory
2661 * Unexpected initialization when address clause present
2663 * Bad alignment for address clause
2665 * Useless type conversions
2667 * Redundant assignment statements and other redundant constructs
2669 * Useless exception handlers
2671 * Accidental hiding of name by child unit
2673 * Access before elaboration detected at compile time
2675 * A range in a `for` loop that is known to be null or might be null
2678 The following section lists compiler switches that are available
2679 to control the handling of warning messages. It is also possible
2680 to exercise much finer control over what warnings are issued and
2681 suppressed using the GNAT pragma Warnings (see the description
2682 of the pragma in the :title:`GNAT_Reference_manual`).
2685 .. index:: -gnatwa (gcc)
2688 *Activate most optional warnings.*
2690 This switch activates most optional warning messages. See the remaining list
2691 in this section for details on optional warning messages that can be
2692 individually controlled. The warnings that are not turned on by this
2696 * :samp:`-gnatwd` (implicit dereferencing)
2698 * :samp:`-gnatw.d` (tag warnings with -gnatw switch)
2700 * :samp:`-gnatwh` (hiding)
2702 * :samp:`-gnatw.h` (holes in record layouts)
2704 * :samp:`-gnatw.k` (redefinition of names in standard)
2706 * :samp:`-gnatwl` (elaboration warnings)
2708 * :samp:`-gnatw.l` (inherited aspects)
2710 * :samp:`-gnatw.n` (atomic synchronization)
2712 * :samp:`-gnatwo` (address clause overlay)
2714 * :samp:`-gnatw.o` (values set by out parameters ignored)
2716 * :samp:`-gnatw.s` (overridden size clause)
2718 * :samp:`-gnatwt` (tracking of deleted conditional code)
2720 * :samp:`-gnatw.u` (unordered enumeration)
2722 * :samp:`-gnatw.w` (use of Warnings Off)
2724 * :samp:`-gnatw.y` (reasons for package needing body)
2726 All other optional warnings are turned on.
2729 .. index:: -gnatwA (gcc)
2732 *Suppress all optional errors.*
2734 This switch suppresses all optional warning messages, see remaining list
2735 in this section for details on optional warning messages that can be
2736 individually controlled. Note that unlike switch *-gnatws*, the
2737 use of switch *-gnatwA* does not suppress warnings that are
2738 normally given unconditionally and cannot be individually controlled
2739 (for example, the warning about a missing exit path in a function).
2740 Also, again unlike switch *-gnatws*, warnings suppressed by
2741 the use of switch *-gnatwA* can be individually turned back
2742 on. For example the use of switch *-gnatwA* followed by
2743 switch *-gnatwd* will suppress all optional warnings except
2744 the warnings for implicit dereferencing.
2746 .. index:: -gnatw.a (gcc)
2749 *Activate warnings on failing assertions.*
2751 .. index:: Assert failures
2753 This switch activates warnings for assertions where the compiler can tell at
2754 compile time that the assertion will fail. Note that this warning is given
2755 even if assertions are disabled. The default is that such warnings are
2759 .. index:: -gnatw.A (gcc)
2762 *Suppress warnings on failing assertions.*
2764 .. index:: Assert failures
2766 This switch suppresses warnings for assertions where the compiler can tell at
2767 compile time that the assertion will fail.
2770 .. index:: -gnatwb (gcc)
2773 *Activate warnings on bad fixed values.*
2775 .. index:: Bad fixed values
2777 .. index:: Fixed-point Small value
2779 .. index:: Small value
2781 This switch activates warnings for static fixed-point expressions whose
2782 value is not an exact multiple of Small. Such values are implementation
2783 dependent, since an implementation is free to choose either of the multiples
2784 that surround the value. GNAT always chooses the closer one, but this is not
2785 required behavior, and it is better to specify a value that is an exact
2786 multiple, ensuring predictable execution. The default is that such warnings
2790 .. index:: -gnatwB (gcc)
2793 *Suppress warnings on bad fixed values.*
2795 This switch suppresses warnings for static fixed-point expressions whose
2796 value is not an exact multiple of Small.
2799 .. index:: -gnatw.b (gcc)
2802 *Activate warnings on biased representation.*
2804 .. index:: Biased representation
2806 This switch activates warnings when a size clause, value size clause, component
2807 clause, or component size clause forces the use of biased representation for an
2808 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2809 to represent 10/11). The default is that such warnings are generated.
2812 .. index:: -gnatwB (gcc)
2815 *Suppress warnings on biased representation.*
2817 This switch suppresses warnings for representation clauses that force the use
2818 of biased representation.
2821 .. index:: -gnatwc (gcc)
2824 *Activate warnings on conditionals.*
2826 .. index:: Conditionals, constant
2828 This switch activates warnings for conditional expressions used in
2829 tests that are known to be True or False at compile time. The default
2830 is that such warnings are not generated.
2831 Note that this warning does
2832 not get issued for the use of boolean variables or constants whose
2833 values are known at compile time, since this is a standard technique
2834 for conditional compilation in Ada, and this would generate too many
2835 false positive warnings.
2837 This warning option also activates a special test for comparisons using
2838 the operators '>=' and' <='.
2839 If the compiler can tell that only the equality condition is possible,
2840 then it will warn that the '>' or '<' part of the test
2841 is useless and that the operator could be replaced by '='.
2842 An example would be comparing a `Natural` variable <= 0.
2844 This warning option also generates warnings if
2845 one or both tests is optimized away in a membership test for integer
2846 values if the result can be determined at compile time. Range tests on
2847 enumeration types are not included, since it is common for such tests
2848 to include an end point.
2850 This warning can also be turned on using *-gnatwa*.
2853 .. index:: -gnatwC (gcc)
2856 *Suppress warnings on conditionals.*
2858 This switch suppresses warnings for conditional expressions used in
2859 tests that are known to be True or False at compile time.
2862 .. index:: -gnatw.c (gcc)
2865 *Activate warnings on missing component clauses.*
2867 .. index:: Component clause, missing
2869 This switch activates warnings for record components where a record
2870 representation clause is present and has component clauses for the
2871 majority, but not all, of the components. A warning is given for each
2872 component for which no component clause is present.
2875 .. index:: -gnatwC (gcc)
2878 *Suppress warnings on missing component clauses.*
2880 This switch suppresses warnings for record components that are
2881 missing a component clause in the situation described above.
2884 .. index:: -gnatwd (gcc)
2887 *Activate warnings on implicit dereferencing.*
2889 If this switch is set, then the use of a prefix of an access type
2890 in an indexed component, slice, or selected component without an
2891 explicit `.all` will generate a warning. With this warning
2892 enabled, access checks occur only at points where an explicit
2893 `.all` appears in the source code (assuming no warnings are
2894 generated as a result of this switch). The default is that such
2895 warnings are not generated.
2898 .. index:: -gnatwD (gcc)
2901 *Suppress warnings on implicit dereferencing.*
2903 .. index:: Implicit dereferencing
2905 .. index:: Dereferencing, implicit
2907 This switch suppresses warnings for implicit dereferences in
2908 indexed components, slices, and selected components.
2911 .. index:: -gnatw.d (gcc)
2914 *Activate tagging of warning and info messages.*
2916 If this switch is set, then warning messages are tagged, with one of the
2920 Used to tag warnings controlled by the switch *-gnatwx* where x
2925 Used to tag warnings controlled by the switch *-gnatw.x* where x
2930 Used to tag elaboration information (info) messages generated when the
2931 static model of elaboration is used and the *-gnatel* switch is set.
2934 - *[restriction warning]*
2935 Used to tag warning messages for restriction violations, activated by use
2936 of the pragma *Restriction_Warnings*.
2939 - *[warning-as-error]*
2940 Used to tag warning messages that have been converted to error messages by
2941 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
2942 the string "error: " rather than "warning: ".
2945 - *[enabled by default]*
2946 Used to tag all other warnings that are always given by default, unless
2947 warnings are completely suppressed using pragma *Warnings(Off)* or
2948 the switch *-gnatws*.
2952 .. index:: -gnatw.d (gcc)
2955 *Deactivate tagging of warning and info messages messages.*
2957 If this switch is set, then warning messages return to the default
2958 mode in which warnings and info messages are not tagged as described above for
2962 .. index:: -gnatwe (gcc)
2963 .. index:: Warnings, treat as error
2966 *Treat warnings and style checks as errors.*
2968 This switch causes warning messages and style check messages to be
2970 The warning string still appears, but the warning messages are counted
2971 as errors, and prevent the generation of an object file. Note that this
2972 is the only -gnatw switch that affects the handling of style check messages.
2973 Note also that this switch has no effect on info (information) messages, which
2974 are not treated as errors if this switch is present.
2977 .. index:: -gnatw.e (gcc)
2980 *Activate every optional warning.*
2982 .. index:: Warnings, activate every optional warning
2984 This switch activates all optional warnings, including those which
2985 are not activated by `-gnatwa`. The use of this switch is not
2986 recommended for normal use. If you turn this switch on, it is almost
2987 certain that you will get large numbers of useless warnings. The
2988 warnings that are excluded from `-gnatwa` are typically highly
2989 specialized warnings that are suitable for use only in code that has
2990 been specifically designed according to specialized coding rules.
2993 .. index:: -gnatwf (gcc)
2996 *Activate warnings on unreferenced formals.*
2998 .. index:: Formals, unreferenced
3000 This switch causes a warning to be generated if a formal parameter
3001 is not referenced in the body of the subprogram. This warning can
3002 also be turned on using *-gnatwu*. The
3003 default is that these warnings are not generated.
3006 .. index:: -gnatwF (gcc)
3009 *Suppress warnings on unreferenced formals.*
3011 This switch suppresses warnings for unreferenced formal
3012 parameters. Note that the
3013 combination *-gnatwu* followed by *-gnatwF* has the
3014 effect of warning on unreferenced entities other than subprogram
3018 .. index:: -gnatwg (gcc)
3021 *Activate warnings on unrecognized pragmas.*
3023 .. index:: Pragmas, unrecognized
3025 This switch causes a warning to be generated if an unrecognized
3026 pragma is encountered. Apart from issuing this warning, the
3027 pragma is ignored and has no effect. The default
3028 is that such warnings are issued (satisfying the Ada Reference
3029 Manual requirement that such warnings appear).
3032 .. index:: -gnatwG (gcc)
3035 *Suppress warnings on unrecognized pragmas.*
3037 This switch suppresses warnings for unrecognized pragmas.
3040 .. index:: -gnatw.g (gcc)
3043 *Warnings used for GNAT sources.*
3045 This switch sets the warning categories that are used by the standard
3046 GNAT style. Currently this is equivalent to
3047 *-gnatwAao.sI.C.V.X*
3048 but more warnings may be added in the future without advanced notice.
3051 .. index:: -gnatwh (gcc)
3054 *Activate warnings on hiding.*
3056 .. index:: Hiding of Declarations
3058 This switch activates warnings on hiding declarations.
3059 A declaration is considered hiding
3060 if it is for a non-overloadable entity, and it declares an entity with the
3061 same name as some other entity that is directly or use-visible. The default
3062 is that such warnings are not generated.
3065 .. index:: -gnatwH (gcc)
3068 *Suppress warnings on hiding.*
3070 This switch suppresses warnings on hiding declarations.
3073 .. index:: -gnatw.h (gcc)
3076 *Activate warnings on holes/gaps in records.*
3078 .. index:: Record Representation (gaps)
3080 This switch activates warnings on component clauses in record
3081 representation clauses that leave holes (gaps) in the record layout.
3082 If this warning option is active, then record representation clauses
3083 should specify a contiguous layout, adding unused fill fields if needed.
3086 .. index:: -gnatw.H (gcc)
3089 *Suppress warnings on holes/gaps in records.*
3091 This switch suppresses warnings on component clauses in record
3092 representation clauses that leave holes (haps) in the record layout.
3095 .. index:: -gnatwi (gcc)
3098 *Activate warnings on implementation units.*
3100 This switch activates warnings for a |with| of an internal GNAT
3101 implementation unit, defined as any unit from the `Ada`,
3102 `Interfaces`, `GNAT`,
3104 hierarchies that is not
3105 documented in either the Ada Reference Manual or the GNAT
3106 Programmer's Reference Manual. Such units are intended only
3107 for internal implementation purposes and should not be |withed|
3108 by user programs. The default is that such warnings are generated
3111 .. index:: -gnatwI (gcc)
3114 *Disable warnings on implementation units.*
3116 This switch disables warnings for a |with| of an internal GNAT
3117 implementation unit.
3120 .. index:: -gnatw.i (gcc)
3123 *Activate warnings on overlapping actuals.*
3125 This switch enables a warning on statically detectable overlapping actuals in
3126 a subprogram call, when one of the actuals is an in-out parameter, and the
3127 types of the actuals are not by-copy types. This warning is off by default.
3130 .. index:: -gnatw.I (gcc)
3133 *Disable warnings on overlapping actuals.*
3135 This switch disables warnings on overlapping actuals in a call..
3138 .. index:: -gnatwj (gcc)
3141 *Activate warnings on obsolescent features (Annex J).*
3143 .. index:: Features, obsolescent
3145 .. index:: Obsolescent features
3147 If this warning option is activated, then warnings are generated for
3148 calls to subprograms marked with `pragma Obsolescent` and
3149 for use of features in Annex J of the Ada Reference Manual. In the
3150 case of Annex J, not all features are flagged. In particular use
3151 of the renamed packages (like `Text_IO`) and use of package
3152 `ASCII` are not flagged, since these are very common and
3153 would generate many annoying positive warnings. The default is that
3154 such warnings are not generated.
3156 In addition to the above cases, warnings are also generated for
3157 GNAT features that have been provided in past versions but which
3158 have been superseded (typically by features in the new Ada standard).
3159 For example, `pragma Ravenscar` will be flagged since its
3160 function is replaced by `pragma Profile(Ravenscar)`, and
3161 `pragma Interface_Name` will be flagged since its function
3162 is replaced by `pragma Import`.
3164 Note that this warning option functions differently from the
3165 restriction `No_Obsolescent_Features` in two respects.
3166 First, the restriction applies only to annex J features.
3167 Second, the restriction does flag uses of package `ASCII`.
3170 .. index:: -gnatwJ (gcc)
3173 *Suppress warnings on obsolescent features (Annex J).*
3175 This switch disables warnings on use of obsolescent features.
3178 .. index:: -gnatwk (gcc)
3181 *Activate warnings on variables that could be constants.*
3183 This switch activates warnings for variables that are initialized but
3184 never modified, and then could be declared constants. The default is that
3185 such warnings are not given.
3188 .. index:: -gnatwK (gcc)
3191 *Suppress warnings on variables that could be constants.*
3193 This switch disables warnings on variables that could be declared constants.
3196 .. index:: -gnatw.k (gcc)
3199 *Activate warnings on redefinition of names in standard.*
3201 This switch activates warnings for declarations that declare a name that
3202 is defined in package Standard. Such declarations can be confusing,
3203 especially since the names in package Standard continue to be directly
3204 visible, meaning that use visibiliy on such redeclared names does not
3205 work as expected. Names of discriminants and components in records are
3206 not included in this check.
3209 .. index:: -gnatwK (gcc)
3212 *Suppress warnings on redefinition of names in standard.*
3214 This switch activates warnings for declarations that declare a name that
3215 is defined in package Standard.
3218 .. index:: -gnatwl (gcc)
3221 *Activate warnings for elaboration pragmas.*
3223 .. index:: Elaboration, warnings
3225 This switch activates warnings for possible elaboration problems,
3226 including suspicious use
3227 of `Elaborate` pragmas, when using the static elaboration model, and
3228 possible situations that may raise `Program_Error` when using the
3229 dynamic elaboration model.
3230 See the section in this guide on elaboration checking for further details.
3231 The default is that such warnings
3235 .. index:: -gnatwL (gcc)
3238 *Suppress warnings for elaboration pragmas.*
3240 This switch suppresses warnings for possible elaboration problems.
3243 .. index:: -gnatw.l (gcc)
3246 *List inherited aspects.*
3248 This switch causes the compiler to list inherited invariants,
3249 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3250 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3253 .. index:: -gnatw.L (gcc)
3256 *Suppress listing of inherited aspects.*
3258 This switch suppresses listing of inherited aspects.
3261 .. index:: -gnatwm (gcc)
3264 *Activate warnings on modified but unreferenced variables.*
3266 This switch activates warnings for variables that are assigned (using
3267 an initialization value or with one or more assignment statements) but
3268 whose value is never read. The warning is suppressed for volatile
3269 variables and also for variables that are renamings of other variables
3270 or for which an address clause is given.
3271 The default is that these warnings are not given.
3274 .. index:: -gnatwM (gcc)
3277 *Disable warnings on modified but unreferenced variables.*
3279 This switch disables warnings for variables that are assigned or
3280 initialized, but never read.
3283 .. index:: -gnatw.m (gcc)
3286 *Activate warnings on suspicious modulus values.*
3288 This switch activates warnings for modulus values that seem suspicious.
3289 The cases caught are where the size is the same as the modulus (e.g.
3290 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3291 with no size clause. The guess in both cases is that 2**x was intended
3292 rather than x. In addition expressions of the form 2*x for small x
3293 generate a warning (the almost certainly accurate guess being that
3294 2**x was intended). The default is that these warnings are given.
3297 .. index:: -gnatw.M (gcc)
3300 *Disable warnings on suspicious modulus values.*
3302 This switch disables warnings for suspicious modulus values.
3305 .. index:: -gnatwn (gcc)
3308 *Set normal warnings mode.*
3310 This switch sets normal warning mode, in which enabled warnings are
3311 issued and treated as warnings rather than errors. This is the default
3312 mode. the switch *-gnatwn* can be used to cancel the effect of
3313 an explicit *-gnatws* or
3314 *-gnatwe*. It also cancels the effect of the
3315 implicit *-gnatwe* that is activated by the
3319 .. index:: -gnatw.n (gcc)
3320 .. index:: Atomic Synchronization, warnings
3323 *Activate warnings on atomic synchronization.*
3325 This switch actives warnings when an access to an atomic variable
3326 requires the generation of atomic synchronization code. These
3327 warnings are off by default.
3329 .. index:: -gnatw.N (gcc)
3332 *Suppress warnings on atomic synchronization.*
3334 .. index:: Atomic Synchronization, warnings
3336 This switch suppresses warnings when an access to an atomic variable
3337 requires the generation of atomic synchronization code.
3340 .. index:: -gnatwo (gcc)
3341 .. index:: Address Clauses, warnings
3344 *Activate warnings on address clause overlays.*
3346 This switch activates warnings for possibly unintended initialization
3347 effects of defining address clauses that cause one variable to overlap
3348 another. The default is that such warnings are generated.
3351 .. index:: -gnatwO (gcc)
3354 *Suppress warnings on address clause overlays.*
3356 This switch suppresses warnings on possibly unintended initialization
3357 effects of defining address clauses that cause one variable to overlap
3361 .. index:: -gnatw.o (gcc)
3364 *Activate warnings on modified but unreferenced out parameters.*
3366 This switch activates warnings for variables that are modified by using
3367 them as actuals for a call to a procedure with an out mode formal, where
3368 the resulting assigned value is never read. It is applicable in the case
3369 where there is more than one out mode formal. If there is only one out
3370 mode formal, the warning is issued by default (controlled by -gnatwu).
3371 The warning is suppressed for volatile
3372 variables and also for variables that are renamings of other variables
3373 or for which an address clause is given.
3374 The default is that these warnings are not given.
3377 .. index:: -gnatw.O (gcc)
3380 *Disable warnings on modified but unreferenced out parameters.*
3382 This switch suppresses warnings for variables that are modified by using
3383 them as actuals for a call to a procedure with an out mode formal, where
3384 the resulting assigned value is never read.
3387 .. index:: -gnatwp (gcc)
3388 .. index:: Inlining, warnings
3391 *Activate warnings on ineffective pragma Inlines.*
3393 This switch activates warnings for failure of front end inlining
3394 (activated by *-gnatN*) to inline a particular call. There are
3395 many reasons for not being able to inline a call, including most
3396 commonly that the call is too complex to inline. The default is
3397 that such warnings are not given.
3398 Warnings on ineffective inlining by the gcc back-end can be activated
3399 separately, using the gcc switch -Winline.
3402 .. index:: -gnatwP (gcc)
3405 *Suppress warnings on ineffective pragma Inlines.*
3407 This switch suppresses warnings on ineffective pragma Inlines. If the
3408 inlining mechanism cannot inline a call, it will simply ignore the
3412 .. index:: -gnatw.p (gcc)
3413 .. index:: Parameter order, warnings
3416 *Activate warnings on parameter ordering.*
3418 This switch activates warnings for cases of suspicious parameter
3419 ordering when the list of arguments are all simple identifiers that
3420 match the names of the formals, but are in a different order. The
3421 warning is suppressed if any use of named parameter notation is used,
3422 so this is the appropriate way to suppress a false positive (and
3423 serves to emphasize that the "misordering" is deliberate). The
3424 default is that such warnings are not given.
3427 .. index:: -gnatw.P (gcc)
3430 *Suppress warnings on parameter ordering.*
3432 This switch suppresses warnings on cases of suspicious parameter
3436 .. index:: -gnatwq (gcc)
3437 .. index:: Parentheses, warnings
3440 *Activate warnings on questionable missing parentheses.*
3442 This switch activates warnings for cases where parentheses are not used and
3443 the result is potential ambiguity from a readers point of view. For example
3444 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3445 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3446 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3447 follow the rule of always parenthesizing to make the association clear, and
3448 this warning switch warns if such parentheses are not present. The default
3449 is that these warnings are given.
3452 .. index:: -gnatwQ (gcc)
3455 *Suppress warnings on questionable missing parentheses.*
3457 This switch suppresses warnings for cases where the association is not
3458 clear and the use of parentheses is preferred.
3461 .. index:: -gnatwr (gcc)
3464 *Activate warnings on redundant constructs.*
3466 This switch activates warnings for redundant constructs. The following
3467 is the current list of constructs regarded as redundant:
3469 * Assignment of an item to itself.
3471 * Type conversion that converts an expression to its own type.
3473 * Use of the attribute `Base` where `typ'Base` is the same
3476 * Use of pragma `Pack` when all components are placed by a record
3477 representation clause.
3479 * Exception handler containing only a reraise statement (raise with no
3480 operand) which has no effect.
3482 * Use of the operator abs on an operand that is known at compile time
3485 * Comparison of boolean expressions to an explicit True value.
3487 The default is that warnings for redundant constructs are not given.
3490 .. index:: -gnatwR (gcc)
3493 *Suppress warnings on redundant constructs.*
3495 This switch suppresses warnings for redundant constructs.
3498 .. index:: -gnatw.r (gcc)
3501 *Activate warnings for object renaming function.*
3503 This switch activates warnings for an object renaming that renames a
3504 function call, which is equivalent to a constant declaration (as
3505 opposed to renaming the function itself). The default is that these
3509 .. index:: -gnatwT (gcc)
3512 *Suppress warnings for object renaming function.*
3514 This switch suppresses warnings for object renaming function.
3517 .. index:: -gnatws (gcc)
3520 *Suppress all warnings.*
3522 This switch completely suppresses the
3523 output of all warning messages from the GNAT front end, including
3524 both warnings that can be controlled by switches described in this
3525 section, and those that are normally given unconditionally. The
3526 effect of this suppress action can only be cancelled by a subsequent
3527 use of the switch *-gnatwn*.
3529 Note that switch *-gnatws* does not suppress
3530 warnings from the *gcc* back end.
3531 To suppress these back end warnings as well, use the switch *-w*
3532 in addition to *-gnatws*. Also this switch has no effect on the
3533 handling of style check messages.
3536 .. index:: -gnatw.s (gcc)
3537 .. index:: Record Representation (component sizes)
3540 *Activate warnings on overridden size clauses.*
3542 This switch activates warnings on component clauses in record
3543 representation clauses where the length given overrides that
3544 specified by an explicit size clause for the component type. A
3545 warning is similarly given in the array case if a specified
3546 component size overrides an explicit size clause for the array
3550 .. index:: -gnatw.S (gcc)
3553 *Suppress warnings on overridden size clauses.*
3555 This switch suppresses warnings on component clauses in record
3556 representation clauses that override size clauses, and similar
3557 warnings when an array component size overrides a size clause.
3560 .. index:: -gnatwt (gcc)
3561 .. index:: Deactivated code, warnings
3562 .. index:: Deleted code, warnings
3565 *Activate warnings for tracking of deleted conditional code.*
3567 This switch activates warnings for tracking of code in conditionals (IF and
3568 CASE statements) that is detected to be dead code which cannot be executed, and
3569 which is removed by the front end. This warning is off by default. This may be
3570 useful for detecting deactivated code in certified applications.
3573 .. index:: -gnatwT (gcc)
3576 *Suppress warnings for tracking of deleted conditional code.*
3578 This switch suppresses warnings for tracking of deleted conditional code.
3581 .. index:: -gnatw.t (gcc)
3584 *Activate warnings on suspicious contracts.*
3586 This switch activates warnings on suspicious contracts. This includes
3587 warnings on suspicious postconditions (whether a pragma `Postcondition` or a
3588 `Post` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3589 `Contract_Cases`). A function postcondition or contract case is suspicious
3590 when no postcondition or contract case for this function mentions the result
3591 of the function. A procedure postcondition or contract case is suspicious
3592 when it only refers to the pre-state of the procedure, because in that case
3593 it should rather be expressed as a precondition. This switch also controls
3594 warnings on suspicious cases of expressions typically found in contracts like
3595 quantified expressions and uses of Update attribute. The default is that such
3596 warnings are generated.
3599 .. index:: -gnatw.T (gcc)
3602 *Suppress warnings on suspicious contracts.*
3604 This switch suppresses warnings on suspicious contracts.
3607 .. index:: -gnatwu (gcc)
3610 *Activate warnings on unused entities.*
3612 This switch activates warnings to be generated for entities that
3613 are declared but not referenced, and for units that are |withed|
3615 referenced. In the case of packages, a warning is also generated if
3616 no entities in the package are referenced. This means that if a with'ed
3617 package is referenced but the only references are in `use`
3618 clauses or `renames`
3619 declarations, a warning is still generated. A warning is also generated
3620 for a generic package that is |withed| but never instantiated.
3621 In the case where a package or subprogram body is compiled, and there
3622 is a |with| on the corresponding spec
3623 that is only referenced in the body,
3624 a warning is also generated, noting that the
3625 |with| can be moved to the body. The default is that
3626 such warnings are not generated.
3627 This switch also activates warnings on unreferenced formals
3628 (it includes the effect of *-gnatwf*).
3631 .. index:: -gnatwU (gcc)
3634 *Suppress warnings on unused entities.*
3636 This switch suppresses warnings for unused entities and packages.
3637 It also turns off warnings on unreferenced formals (and thus includes
3638 the effect of *-gnatwF*).
3641 .. index:: -gnatw.u (gcc)
3644 *Activate warnings on unordered enumeration types.*
3646 This switch causes enumeration types to be considered as conceptually
3647 unordered, unless an explicit pragma `Ordered` is given for the type.
3648 The effect is to generate warnings in clients that use explicit comparisons
3649 or subranges, since these constructs both treat objects of the type as
3650 ordered. (A *client* is defined as a unit that is other than the unit in
3651 which the type is declared, or its body or subunits.) Please refer to
3652 the description of pragma `Ordered` in the
3653 :title:`GNAT Reference Manual` for further details.
3654 The default is that such warnings are not generated.
3657 .. index:: -gnatw.U (gcc)
3660 *Deactivate warnings on unordered enumeration types.*
3662 This switch causes all enumeration types to be considered as ordered, so
3663 that no warnings are given for comparisons or subranges for any type.
3666 .. index:: -gnatwv (gcc)
3667 .. index:: Unassigned variable warnings
3670 *Activate warnings on unassigned variables.*
3672 This switch activates warnings for access to variables which
3673 may not be properly initialized. The default is that
3674 such warnings are generated.
3677 .. index:: -gnatwV (gcc)
3680 *Suppress warnings on unassigned variables.*
3682 This switch suppresses warnings for access to variables which
3683 may not be properly initialized.
3684 For variables of a composite type, the warning can also be suppressed in
3685 Ada 2005 by using a default initialization with a box. For example, if
3686 Table is an array of records whose components are only partially uninitialized,
3687 then the following code:
3691 Tab : Table := (others => <>);
3693 will suppress warnings on subsequent statements that access components
3697 .. index:: -gnatw.v (gcc)
3698 .. index:: bit order warnings
3701 *Activate info messages for non-default bit order.*
3703 This switch activates messages (labeled "info", they are not warnings,
3704 just informational messages) about the effects of non-default bit-order
3705 on records to which a component clause is applied. The effect of specifying
3706 non-default bit ordering is a bit subtle (and changed with Ada 2005), so
3707 these messages, which are given by default, are useful in understanding the
3708 exact consequences of using this feature.
3711 .. index:: -gnatw.V (gcc)
3714 *Suppress info messages for non-default bit order.*
3716 This switch suppresses information messages for the effects of specifying
3717 non-default bit order on record components with component clauses.
3720 .. index:: -gnatww (gcc)
3721 .. index:: String indexing warnings
3724 *Activate warnings on wrong low bound assumption.*
3726 This switch activates warnings for indexing an unconstrained string parameter
3727 with a literal or S'Length. This is a case where the code is assuming that the
3728 low bound is one, which is in general not true (for example when a slice is
3729 passed). The default is that such warnings are generated.
3732 .. index:: -gnatwW (gcc)
3735 *Suppress warnings on wrong low bound assumption.*
3737 This switch suppresses warnings for indexing an unconstrained string parameter
3738 with a literal or S'Length. Note that this warning can also be suppressed
3739 in a particular case by adding an assertion that the lower bound is 1,
3740 as shown in the following example:
3744 procedure K (S : String) is
3745 pragma Assert (S'First = 1);
3749 .. index:: -gnatw.w (gcc)
3750 .. index:: Warnings Off control
3753 *Activate warnings on Warnings Off pragmas.*
3755 This switch activates warnings for use of `pragma Warnings (Off, entity)`
3756 where either the pragma is entirely useless (because it suppresses no
3757 warnings), or it could be replaced by `pragma Unreferenced` or
3758 `pragma Unmodified`.
3759 Also activates warnings for the case of
3760 Warnings (Off, String), where either there is no matching
3761 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
3762 The default is that these warnings are not given.
3765 .. index:: -gnatw.W (gcc)
3768 *Suppress warnings on unnecessary Warnings Off pragmas.*
3770 This switch suppresses warnings for use of `pragma Warnings (Off, ...)`.
3773 .. index:: -gnatwx (gcc)
3774 .. index:: Export/Import pragma warnings
3777 *Activate warnings on Export/Import pragmas.*
3779 This switch activates warnings on Export/Import pragmas when
3780 the compiler detects a possible conflict between the Ada and
3781 foreign language calling sequences. For example, the use of
3782 default parameters in a convention C procedure is dubious
3783 because the C compiler cannot supply the proper default, so
3784 a warning is issued. The default is that such warnings are
3788 .. index:: -gnatwX (gcc)
3791 *Suppress warnings on Export/Import pragmas.*
3793 This switch suppresses warnings on Export/Import pragmas.
3794 The sense of this is that you are telling the compiler that
3795 you know what you are doing in writing the pragma, and it
3796 should not complain at you.
3799 .. index:: -gnatwm (gcc)
3802 *Activate warnings for No_Exception_Propagation mode.*
3804 This switch activates warnings for exception usage when pragma Restrictions
3805 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
3806 explicit exception raises which are not covered by a local handler, and for
3807 exception handlers which do not cover a local raise. The default is that these
3808 warnings are not given.
3812 *Disable warnings for No_Exception_Propagation mode.*
3814 This switch disables warnings for exception usage when pragma Restrictions
3815 (No_Exception_Propagation) is in effect.
3818 .. index:: -gnatwy (gcc)
3819 .. index:: Ada compatibility issues warnings
3822 *Activate warnings for Ada compatibility issues.*
3824 For the most part, newer versions of Ada are upwards compatible
3825 with older versions. For example, Ada 2005 programs will almost
3826 always work when compiled as Ada 2012.
3827 However there are some exceptions (for example the fact that
3828 `some` is now a reserved word in Ada 2012). This
3829 switch activates several warnings to help in identifying
3830 and correcting such incompatibilities. The default is that
3831 these warnings are generated. Note that at one point Ada 2005
3832 was called Ada 0Y, hence the choice of character.
3835 .. index:: -gnatwY (gcc)
3836 .. index:: Ada compatibility issues warnings
3839 *Disable warnings for Ada compatibility issues.*
3841 This switch suppresses the warnings intended to help in identifying
3842 incompatibilities between Ada language versions.
3845 .. index:: -gnatw.y (gcc)
3846 .. index:: Package spec needing body
3849 *Activate information messages for why package spec needs body.*
3851 There are a number of cases in which a package spec needs a body.
3852 For example, the use of pragma Elaborate_Body, or the declaration
3853 of a procedure specification requiring a completion. This switch
3854 causes information messages to be output showing why a package
3855 specification requires a body. This can be useful in the case of
3856 a large package specification which is unexpectedly requiring a
3857 body. The default is that such information messages are not output.
3860 .. index:: -gnatw.Y (gcc)
3861 .. index:: No information messages for why package spec needs body
3864 *Disable information messages for why package spec needs body.*
3866 This switch suppresses the output of information messages showing why
3867 a package specification needs a body.
3870 .. index:: -gnatwz (gcc)
3871 .. index:: Unchecked_Conversion warnings
3874 *Activate warnings on unchecked conversions.*
3876 This switch activates warnings for unchecked conversions
3877 where the types are known at compile time to have different
3878 sizes. The default is that such warnings are generated. Warnings are also
3879 generated for subprogram pointers with different conventions.
3882 .. index:: -gnatwZ (gcc)
3885 *Suppress warnings on unchecked conversions.*
3887 This switch suppresses warnings for unchecked conversions
3888 where the types are known at compile time to have different
3889 sizes or conventions.
3892 .. index:: -gnatw.z (gcc)
3893 .. index:: Size/Alignment warnings
3896 *Activate warnings for size not a multiple of alignment.*
3898 This switch activates warnings for cases of record types with
3899 specified `Size` and `Alignment` attributes where the
3900 size is not a multiple of the alignment, resulting in an object
3901 size that is greater than the specified size. The default
3902 is that such warnings are generated.
3905 .. index:: -gnatw.Z (gcc)
3906 .. index:: Size/Alignment warnings
3909 *Suppress warnings for size not a multiple of alignment.*
3911 This switch suppresses warnings for cases of record types with
3912 specified `Size` and `Alignment` attributes where the
3913 size is not a multiple of the alignment, resulting in an object
3914 size that is greater than the specified size.
3915 The warning can also be
3916 suppressed by giving an explicit `Object_Size` value.
3919 .. index:: -Wunused (gcc)
3922 The warnings controlled by the *-gnatw* switch are generated by
3923 the front end of the compiler. The *GCC* back end can provide
3924 additional warnings and they are controlled by the *-W* switch.
3925 For example, *-Wunused* activates back end
3926 warnings for entities that are declared but not referenced.
3929 .. index:: -Wuninitialized (gcc)
3931 :samp:`-Wuninitialized`
3932 Similarly, *-Wuninitialized* activates
3933 the back end warning for uninitialized variables. This switch must be
3934 used in conjunction with an optimization level greater than zero.
3937 .. index:: -Wstack-usage (gcc)
3939 :samp:`-Wstack-usage={len}`
3940 Warn if the stack usage of a subprogram might be larger than `len` bytes.
3941 See :ref:`Static_Stack_Usage_Analysis` for details.
3944 .. index:: -Wall (gcc)
3947 This switch enables most warnings from the *GCC* back end.
3948 The code generator detects a number of warning situations that are missed
3949 by the *GNAT* front end, and this switch can be used to activate them.
3950 The use of this switch also sets the default front end warning mode to
3951 *-gnatwa*, that is, most front end warnings activated as well.
3957 Conversely, this switch suppresses warnings from the *GCC* back end.
3958 The use of this switch also sets the default front end warning mode to
3959 *-gnatws*, that is, front end warnings suppressed as well.
3962 .. index:: -Werror (gcc)
3965 This switch causes warnings from the *GCC* back end to be treated as
3966 errors. The warning string still appears, but the warning messages are
3967 counted as errors, and prevent the generation of an object file.
3970 A string of warning parameters can be used in the same parameter. For example::
3975 will turn on all optional warnings except for unrecognized pragma warnings,
3976 and also specify that warnings should be treated as errors.
3978 When no switch *-gnatw* is used, this is equivalent to:
4052 .. _Debugging_and_Assertion_Control:
4054 Debugging and Assertion Control
4055 -------------------------------
4059 .. index:: -gnata (gcc)
4064 .. index:: Assertions
4065 .. index:: Precondition
4066 .. index:: Postcondition
4067 .. index:: Type invariants
4068 .. index:: Subtype predicates
4070 The `-gnata` option is equivalent to the following Assertion_Policy pragma::
4072 pragma Assertion_Policy (Check);
4074 Which is a shorthand for::
4076 pragma Assertion_Policy
4078 Static_Predicate => Check,
4079 Dynamic_Predicate => Check,
4083 Post'Class => Check,
4084 Type_Invariant => Check,
4085 Type_Invariant'Class => Check);
4087 The pragmas `Assert` and `Debug` normally have no effect and
4088 are ignored. This switch, where :samp:`a` stands for assert, causes
4089 pragmas `Assert` and `Debug` to be activated. This switch also
4090 causes preconditions, postconditions, subtype predicates, and
4091 type invariants to be activated.
4093 The pragmas have the form::
4095 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4096 pragma Debug (<procedure call>)
4097 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4098 pragma Predicate (<type-local-name>, <Boolean-expression>)
4099 pragma Precondition (<Boolean-expression>, <string-expression>)
4100 pragma Postcondition (<Boolean-expression>, <string-expression>)
4102 The aspects have the form::
4104 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4105 => <Boolean-expression>;
4107 The `Assert` pragma causes `Boolean-expression` to be tested.
4108 If the result is `True`, the pragma has no effect (other than
4109 possible side effects from evaluating the expression). If the result is
4110 `False`, the exception `Assert_Failure` declared in the package
4111 `System.Assertions` is raised (passing `static-string-expression`, if
4112 present, as the message associated with the exception). If no string
4113 expression is given, the default is a string containing the file name and
4114 line number of the pragma.
4116 The `Debug` pragma causes `procedure` to be called. Note that
4117 `pragma Debug` may appear within a declaration sequence, allowing
4118 debugging procedures to be called between declarations.
4120 For the aspect specification, the `<Boolean-expression>` is evaluated.
4121 If the result is `True`, the aspect has no effect. If the result
4122 is `False`, the exception `Assert_Failure` is raised.
4124 .. _Validity_Checking:
4129 .. index:: Validity Checking
4131 The Ada Reference Manual defines the concept of invalid values (see
4132 RM 13.9.1). The primary source of invalid values is uninitialized
4133 variables. A scalar variable that is left uninitialized may contain
4134 an invalid value; the concept of invalid does not apply to access or
4137 It is an error to read an invalid value, but the RM does not require
4138 run-time checks to detect such errors, except for some minimal
4139 checking to prevent erroneous execution (i.e. unpredictable
4140 behavior). This corresponds to the *-gnatVd* switch below,
4141 which is the default. For example, by default, if the expression of a
4142 case statement is invalid, it will raise Constraint_Error rather than
4143 causing a wild jump, and if an array index on the left-hand side of an
4144 assignment is invalid, it will raise Constraint_Error rather than
4145 overwriting an arbitrary memory location.
4147 The *-gnatVa* may be used to enable additional validity checks,
4148 which are not required by the RM. These checks are often very
4149 expensive (which is why the RM does not require them). These checks
4150 are useful in tracking down uninitialized variables, but they are
4151 not usually recommended for production builds, and in particular
4152 we do not recommend using these extra validity checking options in
4153 combination with optimization, since this can confuse the optimizer.
4154 If performance is a consideration, leading to the need to optimize,
4155 then the validity checking options should not be used.
4157 The other *-gnatV*\ ``x`` switches below allow finer-grained
4158 control; you can enable whichever validity checks you desire. However,
4159 for most debugging purposes, *-gnatVa* is sufficient, and the
4160 default *-gnatVd* (i.e. standard Ada behavior) is usually
4161 sufficient for non-debugging use.
4163 The *-gnatB* switch tells the compiler to assume that all
4164 values are valid (that is, within their declared subtype range)
4165 except in the context of a use of the Valid attribute. This means
4166 the compiler can generate more efficient code, since the range
4167 of values is better known at compile time. However, an uninitialized
4168 variable can cause wild jumps and memory corruption in this mode.
4170 The *-gnatV*\ ``x`` switch allows control over the validity
4171 checking mode as described below.
4172 The ``x`` argument is a string of letters that
4173 indicate validity checks that are performed or not performed in addition
4174 to the default checks required by Ada as described above.
4177 .. index:: -gnatVa (gcc)
4180 *All validity checks.*
4182 All validity checks are turned on.
4183 That is, *-gnatVa* is
4184 equivalent to *gnatVcdfimorst*.
4187 .. index:: -gnatVc (gcc)
4190 *Validity checks for copies.*
4192 The right hand side of assignments, and the initializing values of
4193 object declarations are validity checked.
4196 .. index:: -gnatVd (gcc)
4199 *Default (RM) validity checks.*
4201 Some validity checks are done by default following normal Ada semantics
4203 A check is done in case statements that the expression is within the range
4204 of the subtype. If it is not, Constraint_Error is raised.
4205 For assignments to array components, a check is done that the expression used
4206 as index is within the range. If it is not, Constraint_Error is raised.
4207 Both these validity checks may be turned off using switch *-gnatVD*.
4208 They are turned on by default. If *-gnatVD* is specified, a subsequent
4209 switch *-gnatVd* will leave the checks turned on.
4210 Switch *-gnatVD* should be used only if you are sure that all such
4211 expressions have valid values. If you use this switch and invalid values
4212 are present, then the program is erroneous, and wild jumps or memory
4213 overwriting may occur.
4216 .. index:: -gnatVe (gcc)
4219 *Validity checks for elementary components.*
4221 In the absence of this switch, assignments to record or array components are
4222 not validity checked, even if validity checks for assignments generally
4223 (*-gnatVc*) are turned on. In Ada, assignment of composite values do not
4224 require valid data, but assignment of individual components does. So for
4225 example, there is a difference between copying the elements of an array with a
4226 slice assignment, compared to assigning element by element in a loop. This
4227 switch allows you to turn off validity checking for components, even when they
4228 are assigned component by component.
4231 .. index:: -gnatVf (gcc)
4234 *Validity checks for floating-point values.*
4236 In the absence of this switch, validity checking occurs only for discrete
4237 values. If *-gnatVf* is specified, then validity checking also applies
4238 for floating-point values, and NaNs and infinities are considered invalid,
4239 as well as out of range values for constrained types. Note that this means
4240 that standard IEEE infinity mode is not allowed. The exact contexts
4241 in which floating-point values are checked depends on the setting of other
4242 options. For example, *-gnatVif* or *-gnatVfi*
4243 (the order does not matter) specifies that floating-point parameters of mode
4244 `in` should be validity checked.
4247 .. index:: -gnatVi (gcc)
4250 *Validity checks for `in` mode parameters.*
4252 Arguments for parameters of mode `in` are validity checked in function
4253 and procedure calls at the point of call.
4256 .. index:: -gnatVm (gcc)
4259 *Validity checks for `in out` mode parameters.*
4261 Arguments for parameters of mode `in out` are validity checked in
4262 procedure calls at the point of call. The `'m'` here stands for
4263 modify, since this concerns parameters that can be modified by the call.
4264 Note that there is no specific option to test `out` parameters,
4265 but any reference within the subprogram will be tested in the usual
4266 manner, and if an invalid value is copied back, any reference to it
4267 will be subject to validity checking.
4270 .. index:: -gnatVn (gcc)
4273 *No validity checks.*
4275 This switch turns off all validity checking, including the default checking
4276 for case statements and left hand side subscripts. Note that the use of
4277 the switch *-gnatp* suppresses all run-time checks, including
4278 validity checks, and thus implies *-gnatVn*. When this switch
4279 is used, it cancels any other *-gnatV* previously issued.
4282 .. index:: -gnatVo (gcc)
4285 *Validity checks for operator and attribute operands.*
4287 Arguments for predefined operators and attributes are validity checked.
4288 This includes all operators in package `Standard`,
4289 the shift operators defined as intrinsic in package `Interfaces`
4290 and operands for attributes such as `Pos`. Checks are also made
4291 on individual component values for composite comparisons, and on the
4292 expressions in type conversions and qualified expressions. Checks are
4293 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4296 .. index:: -gnatVp (gcc)
4299 *Validity checks for parameters.*
4301 This controls the treatment of parameters within a subprogram (as opposed
4302 to *-gnatVi* and *-gnatVm* which control validity testing
4303 of parameters on a call. If either of these call options is used, then
4304 normally an assumption is made within a subprogram that the input arguments
4305 have been validity checking at the point of call, and do not need checking
4306 again within a subprogram). If *-gnatVp* is set, then this assumption
4307 is not made, and parameters are not assumed to be valid, so their validity
4308 will be checked (or rechecked) within the subprogram.
4311 .. index:: -gnatVr (gcc)
4314 *Validity checks for function returns.*
4316 The expression in `return` statements in functions is validity
4320 .. index:: -gnatVs (gcc)
4323 *Validity checks for subscripts.*
4325 All subscripts expressions are checked for validity, whether they appear
4326 on the right side or left side (in default mode only left side subscripts
4327 are validity checked).
4330 .. index:: -gnatVt (gcc)
4333 *Validity checks for tests.*
4335 Expressions used as conditions in `if`, `while` or `exit`
4336 statements are checked, as well as guard expressions in entry calls.
4339 The *-gnatV* switch may be followed by a string of letters
4340 to turn on a series of validity checking options.
4341 For example, :samp:`-gnatVcr`
4342 specifies that in addition to the default validity checking, copies and
4343 function return expressions are to be validity checked.
4344 In order to make it easier to specify the desired combination of effects,
4345 the upper case letters `CDFIMORST` may
4346 be used to turn off the corresponding lower case option.
4347 Thus :samp:`-gnatVaM` turns on all validity checking options except for
4348 checking of `**in out**` procedure arguments.
4350 The specification of additional validity checking generates extra code (and
4351 in the case of *-gnatVa* the code expansion can be substantial).
4352 However, these additional checks can be very useful in detecting
4353 uninitialized variables, incorrect use of unchecked conversion, and other
4354 errors leading to invalid values. The use of pragma `Initialize_Scalars`
4355 is useful in conjunction with the extra validity checking, since this
4356 ensures that wherever possible uninitialized variables have invalid values.
4358 See also the pragma `Validity_Checks` which allows modification of
4359 the validity checking mode at the program source level, and also allows for
4360 temporary disabling of validity checks.
4367 .. index:: Style checking
4369 .. index:: -gnaty (gcc)
4371 The *-gnatyx* switch causes the compiler to
4372 enforce specified style rules. A limited set of style rules has been used
4373 in writing the GNAT sources themselves. This switch allows user programs
4374 to activate all or some of these checks. If the source program fails a
4375 specified style check, an appropriate message is given, preceded by
4376 the character sequence '(style)'. This message does not prevent
4377 successful compilation (unless the *-gnatwe* switch is used).
4379 Note that this is by no means intended to be a general facility for
4380 checking arbitrary coding standards. It is simply an embedding of the
4381 style rules we have chosen for the GNAT sources. If you are starting
4382 a project which does not have established style standards, you may
4383 find it useful to adopt the entire set of GNAT coding standards, or
4384 some subset of them.
4386 .. only:: PRO or GPL
4388 If you already have an established set of coding
4389 standards, then the selected style checking options may
4390 indeed correspond to choices you have made, but for general checking
4391 of an existing set of coding rules, you should look to the gnatcheck
4392 tool, which is designed for that purpose.
4394 The string `x` is a sequence of letters or digits
4395 indicating the particular style
4396 checks to be performed. The following checks are defined:
4399 .. index:: -gnaty[0-9] (gcc)
4402 *Specify indentation level.*
4404 If a digit from 1-9 appears
4405 in the string after *-gnaty*
4406 then proper indentation is checked, with the digit indicating the
4407 indentation level required. A value of zero turns off this style check.
4408 The general style of required indentation is as specified by
4409 the examples in the Ada Reference Manual. Full line comments must be
4410 aligned with the `--` starting on a column that is a multiple of
4411 the alignment level, or they may be aligned the same way as the following
4412 non-blank line (this is useful when full line comments appear in the middle
4413 of a statement, or they may be aligned with the source line on the previous
4416 .. index:: -gnatya (gcc)
4419 *Check attribute casing.*
4421 Attribute names, including the case of keywords such as `digits`
4422 used as attributes names, must be written in mixed case, that is, the
4423 initial letter and any letter following an underscore must be uppercase.
4424 All other letters must be lowercase.
4427 .. index:: -gnatyA (gcc)
4430 *Use of array index numbers in array attributes.*
4432 When using the array attributes First, Last, Range,
4433 or Length, the index number must be omitted for one-dimensional arrays
4434 and is required for multi-dimensional arrays.
4437 .. index:: -gnatyb (gcc)
4440 *Blanks not allowed at statement end.*
4442 Trailing blanks are not allowed at the end of statements. The purpose of this
4443 rule, together with h (no horizontal tabs), is to enforce a canonical format
4444 for the use of blanks to separate source tokens.
4447 .. index:: -gnatyB (gcc)
4450 *Check Boolean operators.*
4452 The use of AND/OR operators is not permitted except in the cases of modular
4453 operands, array operands, and simple stand-alone boolean variables or
4454 boolean constants. In all other cases `and then`/`or else` are
4458 .. index:: -gnatyc (gcc)
4461 *Check comments, double space.*
4463 Comments must meet the following set of rules:
4465 * The '`--`' that starts the column must either start in column one,
4466 or else at least one blank must precede this sequence.
4468 * Comments that follow other tokens on a line must have at least one blank
4469 following the '`--`' at the start of the comment.
4471 * Full line comments must have at least two blanks following the
4472 '`--`' that starts the comment, with the following exceptions.
4474 * A line consisting only of the '`--`' characters, possibly preceded
4475 by blanks is permitted.
4477 * A comment starting with '`--x`' where `x` is a special character
4479 This allows proper processing of the output generated by specialized tools
4480 including *gnatprep* (where '`--!`' is used) and the SPARK
4482 language (where '`--#`' is used). For the purposes of this rule, a
4483 special character is defined as being in one of the ASCII ranges
4484 `16#21#...16#2F#` or `16#3A#...16#3F#`.
4485 Note that this usage is not permitted
4486 in GNAT implementation units (i.e., when *-gnatg* is used).
4488 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4489 permitted. This allows the construction of box comments where lines of minus
4490 signs are used to form the top and bottom of the box.
4492 * A comment that starts and ends with '`--`' is permitted as long as at
4493 least one blank follows the initial '`--`'. Together with the preceding
4494 rule, this allows the construction of box comments, as shown in the following
4499 ---------------------------
4500 -- This is a box comment --
4501 -- with two text lines. --
4502 ---------------------------
4505 .. index:: -gnatyC (gcc)
4508 *Check comments, single space.*
4510 This is identical to `c` except that only one space
4511 is required following the `--` of a comment instead of two.
4514 .. index:: -gnatyd (gcc)
4517 *Check no DOS line terminators present.*
4519 All lines must be terminated by a single ASCII.LF
4520 character (in particular the DOS line terminator sequence CR/LF is not
4524 .. index:: -gnatye (gcc)
4527 *Check end/exit labels.*
4529 Optional labels on `end` statements ending subprograms and on
4530 `exit` statements exiting named loops, are required to be present.
4533 .. index:: -gnatyf (gcc)
4536 *No form feeds or vertical tabs.*
4538 Neither form feeds nor vertical tab characters are permitted
4542 .. index:: -gnatyg (gcc)
4547 The set of style check switches is set to match that used by the GNAT sources.
4548 This may be useful when developing code that is eventually intended to be
4549 incorporated into GNAT. Currently this is equivalent to *-gnatwydISux*)
4550 but additional style switches may be added to this set in the future without
4554 .. index:: -gnatyh (gcc)
4557 *No horizontal tabs.*
4559 Horizontal tab characters are not permitted in the source text.
4560 Together with the b (no blanks at end of line) check, this
4561 enforces a canonical form for the use of blanks to separate
4565 .. index:: -gnatyi (gcc)
4568 *Check if-then layout.*
4570 The keyword `then` must appear either on the same
4571 line as corresponding `if`, or on a line on its own, lined
4575 .. index:: -gnatyI (gcc)
4578 *check mode IN keywords.*
4580 Mode `in` (the default mode) is not
4581 allowed to be given explicitly. `in out` is fine,
4582 but not `in` on its own.
4585 .. index:: -gnatyk (gcc)
4588 *Check keyword casing.*
4590 All keywords must be in lower case (with the exception of keywords
4591 such as `digits` used as attribute names to which this check
4595 .. index:: -gnatyl (gcc)
4600 Layout of statement and declaration constructs must follow the
4601 recommendations in the Ada Reference Manual, as indicated by the
4602 form of the syntax rules. For example an `else` keyword must
4603 be lined up with the corresponding `if` keyword.
4605 There are two respects in which the style rule enforced by this check
4606 option are more liberal than those in the Ada Reference Manual. First
4607 in the case of record declarations, it is permissible to put the
4608 `record` keyword on the same line as the `type` keyword, and
4609 then the `end` in `end record` must line up under `type`.
4610 This is also permitted when the type declaration is split on two lines.
4611 For example, any of the following three layouts is acceptable:
4632 Second, in the case of a block statement, a permitted alternative
4633 is to put the block label on the same line as the `declare` or
4634 `begin` keyword, and then line the `end` keyword up under
4635 the block label. For example both the following are permitted:
4652 The same alternative format is allowed for loops. For example, both of
4653 the following are permitted:
4657 Clear : while J < 10 loop
4667 .. index:: -gnatyLnnn (gcc)
4670 *Set maximum nesting level.*
4672 The maximum level of nesting of constructs (including subprograms, loops,
4673 blocks, packages, and conditionals) may not exceed the given value
4674 *nnn*. A value of zero disconnects this style check.
4677 .. index:: -gnatym (gcc)
4680 *Check maximum line length.*
4682 The length of source lines must not exceed 79 characters, including
4683 any trailing blanks. The value of 79 allows convenient display on an
4684 80 character wide device or window, allowing for possible special
4685 treatment of 80 character lines. Note that this count is of
4686 characters in the source text. This means that a tab character counts
4687 as one character in this count and a wide character sequence counts as
4688 a single character (however many bytes are needed in the encoding).
4691 .. index:: -gnatyMnnn (gcc)
4694 *Set maximum line length.*
4696 The length of lines must not exceed the
4697 given value *nnn*. The maximum value that can be specified is 32767.
4698 If neither style option for setting the line length is used, then the
4699 default is 255. This also controls the maximum length of lexical elements,
4700 where the only restriction is that they must fit on a single line.
4703 .. index:: -gnatyn (gcc)
4706 *Check casing of entities in Standard.*
4708 Any identifier from Standard must be cased
4709 to match the presentation in the Ada Reference Manual (for example,
4710 `Integer` and `ASCII.NUL`).
4713 .. index:: -gnatyN (gcc)
4716 *Turn off all style checks.*
4718 All style check options are turned off.
4721 .. index:: -gnatyo (gcc)
4724 *Check order of subprogram bodies.*
4726 All subprogram bodies in a given scope
4727 (e.g., a package body) must be in alphabetical order. The ordering
4728 rule uses normal Ada rules for comparing strings, ignoring casing
4729 of letters, except that if there is a trailing numeric suffix, then
4730 the value of this suffix is used in the ordering (e.g., Junk2 comes
4734 .. index:: -gnatyO (gcc)
4737 *Check that overriding subprograms are explicitly marked as such.*
4739 This applies to all subprograms of a derived type that override a primitive
4740 operation of the type, for both tagged and untagged types. In particular,
4741 the declaration of a primitive operation of a type extension that overrides
4742 an inherited operation must carry an overriding indicator. Another case is
4743 the declaration of a function that overrides a predefined operator (such
4744 as an equality operator).
4747 .. index:: -gnatyp (gcc)
4750 *Check pragma casing.*
4752 Pragma names must be written in mixed case, that is, the
4753 initial letter and any letter following an underscore must be uppercase.
4754 All other letters must be lowercase. An exception is that SPARK_Mode is
4755 allowed as an alternative for Spark_Mode.
4758 .. index:: -gnatyr (gcc)
4763 All identifier references must be cased in the same way as the
4764 corresponding declaration. No specific casing style is imposed on
4765 identifiers. The only requirement is for consistency of references
4769 .. index:: -gnatys (gcc)
4772 *Check separate specs.*
4774 Separate declarations ('specs') are required for subprograms (a
4775 body is not allowed to serve as its own declaration). The only
4776 exception is that parameterless library level procedures are
4777 not required to have a separate declaration. This exception covers
4778 the most frequent form of main program procedures.
4781 .. index:: -gnatyS (gcc)
4784 *Check no statements after then/else.*
4786 No statements are allowed
4787 on the same line as a `then` or `else` keyword following the
4788 keyword in an `if` statement. `or else` and `and then` are not
4789 affected, and a special exception allows a pragma to appear after `else`.
4792 .. index:: -gnatyt (gcc)
4795 *Check token spacing.*
4797 The following token spacing rules are enforced:
4799 * The keywords `abs` and `not` must be followed by a space.
4801 * The token `=>` must be surrounded by spaces.
4803 * The token `<>` must be preceded by a space or a left parenthesis.
4805 * Binary operators other than `**` must be surrounded by spaces.
4806 There is no restriction on the layout of the `**` binary operator.
4808 * Colon must be surrounded by spaces.
4810 * Colon-equal (assignment, initialization) must be surrounded by spaces.
4812 * Comma must be the first non-blank character on the line, or be
4813 immediately preceded by a non-blank character, and must be followed
4816 * If the token preceding a left parenthesis ends with a letter or digit, then
4817 a space must separate the two tokens.
4819 * If the token following a right parenthesis starts with a letter or digit, then
4820 a space must separate the two tokens.
4822 * A right parenthesis must either be the first non-blank character on
4823 a line, or it must be preceded by a non-blank character.
4825 * A semicolon must not be preceded by a space, and must not be followed by
4826 a non-blank character.
4828 * A unary plus or minus may not be followed by a space.
4830 * A vertical bar must be surrounded by spaces.
4832 Exactly one blank (and no other white space) must appear between
4833 a `not` token and a following `in` token.
4836 .. index:: -gnatyu (gcc)
4839 *Check unnecessary blank lines.*
4841 Unnecessary blank lines are not allowed. A blank line is considered
4842 unnecessary if it appears at the end of the file, or if more than
4843 one blank line occurs in sequence.
4846 .. index:: -gnatyx (gcc)
4849 *Check extra parentheses.*
4851 Unnecessary extra level of parentheses (C-style) are not allowed
4852 around conditions in `if` statements, `while` statements and
4856 .. index:: -gnatyy (gcc)
4859 *Set all standard style check options.*
4861 This is equivalent to `gnaty3aAbcefhiklmnprst`, that is all checking
4862 options enabled with the exception of *-gnatyB*, *-gnatyd*,
4863 *-gnatyI*, *-gnatyLnnn*, *-gnatyo*, *-gnatyO*,
4864 *-gnatyS*, *-gnatyu*, and *-gnatyx*.
4867 .. index:: -gnaty- (gcc)
4870 *Remove style check options.*
4872 This causes any subsequent options in the string to act as canceling the
4873 corresponding style check option. To cancel maximum nesting level control,
4874 use *L* parameter witout any integer value after that, because any
4875 digit following *-* in the parameter string of the *-gnaty*
4876 option will be threated as canceling indentation check. The same is true
4877 for *M* parameter. *y* and *N* parameters are not
4881 .. index:: -gnaty+ (gcc)
4884 *Enable style check options.*
4886 This causes any subsequent options in the string to enable the corresponding
4887 style check option. That is, it cancels the effect of a previous -,
4891 .. end of switch description (leave this comment to ease automatic parsing for
4894 In the above rules, appearing in column one is always permitted, that is,
4895 counts as meeting either a requirement for a required preceding space,
4896 or as meeting a requirement for no preceding space.
4898 Appearing at the end of a line is also always permitted, that is, counts
4899 as meeting either a requirement for a following space, or as meeting
4900 a requirement for no following space.
4902 If any of these style rules is violated, a message is generated giving
4903 details on the violation. The initial characters of such messages are
4904 always '`(style)`'. Note that these messages are treated as warning
4905 messages, so they normally do not prevent the generation of an object
4906 file. The *-gnatwe* switch can be used to treat warning messages,
4907 including style messages, as fatal errors.
4909 The switch :samp:`-gnaty` on its own (that is not
4910 followed by any letters or digits) is equivalent
4911 to the use of *-gnatyy* as described above, that is all
4912 built-in standard style check options are enabled.
4914 The switch :samp:`-gnatyN` clears any previously set style checks.
4916 .. _Run-Time_Checks:
4921 .. index:: Division by zero
4923 .. index:: Access before elaboration
4925 .. index:: Checks, division by zero
4927 .. index:: Checks, access before elaboration
4929 .. index:: Checks, stack overflow checking
4931 By default, the following checks are suppressed: stack overflow
4932 checks, and checks for access before elaboration on subprogram
4933 calls. All other checks, including overflow checks, range checks and
4934 array bounds checks, are turned on by default. The following *gcc*
4935 switches refine this default behavior.
4937 .. index:: -gnatp (gcc)
4940 .. index:: Suppressing checks
4942 .. index:: Checks, suppressing
4944 This switch causes the unit to be compiled
4945 as though `pragma Suppress (All_checks)`
4946 had been present in the source. Validity checks are also eliminated (in
4947 other words *-gnatp* also implies *-gnatVn*.
4948 Use this switch to improve the performance
4949 of the code at the expense of safety in the presence of invalid data or
4952 Note that when checks are suppressed, the compiler is allowed, but not
4953 required, to omit the checking code. If the run-time cost of the
4954 checking code is zero or near-zero, the compiler will generate it even
4955 if checks are suppressed. In particular, if the compiler can prove
4956 that a certain check will necessarily fail, it will generate code to
4957 do an unconditional 'raise', even if checks are suppressed. The
4958 compiler warns in this case. Another case in which checks may not be
4959 eliminated is when they are embedded in certain run time routines such
4960 as math library routines.
4962 Of course, run-time checks are omitted whenever the compiler can prove
4963 that they will not fail, whether or not checks are suppressed.
4965 Note that if you suppress a check that would have failed, program
4966 execution is erroneous, which means the behavior is totally
4967 unpredictable. The program might crash, or print wrong answers, or
4968 do anything else. It might even do exactly what you wanted it to do
4969 (and then it might start failing mysteriously next week or next
4970 year). The compiler will generate code based on the assumption that
4971 the condition being checked is true, which can result in erroneous
4972 execution if that assumption is wrong.
4974 The checks subject to suppression include all the checks defined by the Ada
4975 standard, the additional implementation defined checks `Alignment_Check`,
4976 `Duplicated_Tag_Check`, `Predicate_Check`, Container_Checks, Tampering_Check,
4977 and `Validity_Check`, as well as any checks introduced using `pragma
4978 Check_Name`. Note that `Atomic_Synchronization` is not automatically
4979 suppressed by use of this option.
4981 If the code depends on certain checks being active, you can use
4982 pragma `Unsuppress` either as a configuration pragma or as
4983 a local pragma to make sure that a specified check is performed
4984 even if *gnatp* is specified.
4986 The *-gnatp* switch has no effect if a subsequent
4987 *-gnat-p* switch appears.
4990 .. index:: -gnat-p (gcc)
4991 .. index:: Suppressing checks
4992 .. index:: Checks, suppressing
4996 This switch cancels the effect of a previous *gnatp* switch.
4999 .. index:: -gnato?? (gcc)
5000 .. index:: Overflow checks
5001 .. index:: Overflow mode
5002 .. index:: Check, overflow
5005 This switch controls the mode used for computing intermediate
5006 arithmetic integer operations, and also enables overflow checking.
5007 For a full description of overflow mode and checking control, see
5008 the 'Overflow Check Handling in GNAT' appendix in this
5011 Overflow checks are always enabled by this switch. The argument
5012 controls the mode, using the codes
5016 In STRICT mode, intermediate operations are always done using the
5017 base type, and overflow checking ensures that the result is within
5018 the base type range.
5022 In MINIMIZED mode, overflows in intermediate operations are avoided
5023 where possible by using a larger integer type for the computation
5024 (typically `Long_Long_Integer`). Overflow checking ensures that
5025 the result fits in this larger integer type.
5029 In ELIMINATED mode, overflows in intermediate operations are avoided
5030 by using multi-precision arithmetic. In this case, overflow checking
5031 has no effect on intermediate operations (since overflow is impossible).
5033 If two digits are present after *-gnato* then the first digit
5034 sets the mode for expressions outside assertions, and the second digit
5035 sets the mode for expressions within assertions. Here assertions is used
5036 in the technical sense (which includes for example precondition and
5037 postcondition expressions).
5039 If one digit is present, the corresponding mode is applicable to both
5040 expressions within and outside assertion expressions.
5042 If no digits are present, the default is to enable overflow checks
5043 and set STRICT mode for both kinds of expressions. This is compatible
5044 with the use of *-gnato* in previous versions of GNAT.
5046 .. index:: Machine_Overflows
5048 Note that the *-gnato??* switch does not affect the code generated
5049 for any floating-point operations; it applies only to integer semantics.
5050 For floating-point, GNAT has the `Machine_Overflows`
5051 attribute set to `False` and the normal mode of operation is to
5052 generate IEEE NaN and infinite values on overflow or invalid operations
5053 (such as dividing 0.0 by 0.0).
5055 The reason that we distinguish overflow checking from other kinds of
5056 range constraint checking is that a failure of an overflow check, unlike
5057 for example the failure of a range check, can result in an incorrect
5058 value, but cannot cause random memory destruction (like an out of range
5059 subscript), or a wild jump (from an out of range case value). Overflow
5060 checking is also quite expensive in time and space, since in general it
5061 requires the use of double length arithmetic.
5063 Note again that the default is *-gnato11* (equivalent to *-gnato1*),
5064 so overflow checking is performed in STRICT mode by default.
5067 .. index:: -gnatE (gcc)
5068 .. index:: Elaboration checks
5069 .. index:: Check, elaboration
5072 Enables dynamic checks for access-before-elaboration
5073 on subprogram calls and generic instantiations.
5074 Note that *-gnatE* is not necessary for safety, because in the
5075 default mode, GNAT ensures statically that the checks would not fail.
5076 For full details of the effect and use of this switch,
5077 :ref:`Compiling_with_gcc`.
5080 .. index:: -fstack-check (gcc)
5081 .. index:: Stack Overflow Checking
5082 .. index:: Checks, stack overflow checking
5084 :samp:`-fstack-check`
5085 Activates stack overflow checking. For full details of the effect and use of
5086 this switch see :ref:`Stack_Overflow_Checking`.
5088 .. index:: Unsuppress
5090 The setting of these switches only controls the default setting of the
5091 checks. You may modify them using either `Suppress` (to remove
5092 checks) or `Unsuppress` (to add back suppressed checks) pragmas in
5096 .. _Using_gcc_for_Syntax_Checking:
5098 Using *gcc* for Syntax Checking
5099 -------------------------------
5101 .. index:: -gnats (gcc)
5104 The `s` stands for 'syntax'.
5106 Run GNAT in syntax checking only mode. For
5107 example, the command
5111 $ gcc -c -gnats x.adb
5113 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5114 series of files in a single command
5115 , and can use wild cards to specify such a group of files.
5116 Note that you must specify the *-c* (compile
5117 only) flag in addition to the *-gnats* flag.
5119 You may use other switches in conjunction with *-gnats*. In
5120 particular, *-gnatl* and *-gnatv* are useful to control the
5121 format of any generated error messages.
5123 When the source file is empty or contains only empty lines and/or comments,
5124 the output is a warning:
5129 $ gcc -c -gnats -x ada toto.txt
5130 toto.txt:1:01: warning: empty file, contains no compilation units
5134 Otherwise, the output is simply the error messages, if any. No object file or
5135 ALI file is generated by a syntax-only compilation. Also, no units other
5136 than the one specified are accessed. For example, if a unit `X`
5137 |withs| a unit `Y`, compiling unit `X` in syntax
5138 check only mode does not access the source file containing unit
5141 .. index:: Multiple units, syntax checking
5143 Normally, GNAT allows only a single unit in a source file. However, this
5144 restriction does not apply in syntax-check-only mode, and it is possible
5145 to check a file containing multiple compilation units concatenated
5146 together. This is primarily used by the `gnatchop` utility
5147 (:ref:`Renaming_Files_with_gnatchop`).
5149 .. _Using_gcc_for_Semantic_Checking:
5151 Using *gcc* for Semantic Checking
5152 ---------------------------------
5156 .. index:: -gnatc (gcc)
5159 The `c` stands for 'check'.
5160 Causes the compiler to operate in semantic check mode,
5161 with full checking for all illegalities specified in the
5162 Ada Reference Manual, but without generation of any object code
5163 (no object file is generated).
5165 Because dependent files must be accessed, you must follow the GNAT
5166 semantic restrictions on file structuring to operate in this mode:
5168 * The needed source files must be accessible
5169 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5171 * Each file must contain only one compilation unit.
5173 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5175 The output consists of error messages as appropriate. No object file is
5176 generated. An :file:`ALI` file is generated for use in the context of
5177 cross-reference tools, but this file is marked as not being suitable
5178 for binding (since no object file is generated).
5179 The checking corresponds exactly to the notion of
5180 legality in the Ada Reference Manual.
5182 Any unit can be compiled in semantics-checking-only mode, including
5183 units that would not normally be compiled (subunits,
5184 and specifications where a separate body is present).
5186 .. _Compiling_Different_Versions_of_Ada:
5188 Compiling Different Versions of Ada
5189 -----------------------------------
5191 The switches described in this section allow you to explicitly specify
5192 the version of the Ada language that your programs are written in.
5193 The default mode is Ada 2012,
5194 but you can also specify Ada 95, Ada 2005 mode, or
5195 indicate Ada 83 compatibility mode.
5198 .. index:: Compatibility with Ada 83
5199 .. index:: -gnat83 (gcc)
5200 .. index:: ACVC, Ada 83 tests
5201 .. index:: Ada 83 mode
5203 :samp:`-gnat83` (Ada 83 Compatibility Mode)
5204 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5205 specifies that the program is to be compiled in Ada 83 mode. With
5206 *-gnat83*, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5207 semantics where this can be done easily.
5208 It is not possible to guarantee this switch does a perfect
5209 job; some subtle tests, such as are
5210 found in earlier ACVC tests (and that have been removed from the ACATS suite
5211 for Ada 95), might not compile correctly.
5212 Nevertheless, this switch may be useful in some circumstances, for example
5213 where, due to contractual reasons, existing code needs to be maintained
5214 using only Ada 83 features.
5216 With few exceptions (most notably the need to use `<>` on
5217 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5218 the use of the new Ada 95 / Ada 2005
5219 reserved words, and the use of packages
5220 with optional bodies), it is not necessary to specify the
5221 *-gnat83* switch when compiling Ada 83 programs, because, with rare
5222 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5223 a correct Ada 83 program is usually also a correct program
5224 in these later versions of the language standard. For further information
5225 please refer to the `Compatibility_and_Porting_Guide` chapter in the
5226 :title:`GNAT Reference Manual`.
5229 .. index:: -gnat95 (gcc)
5230 .. index:: Ada 95 mode
5232 :samp:`-gnat95` (Ada 95 mode)
5233 This switch directs the compiler to implement the Ada 95 version of the
5235 Since Ada 95 is almost completely upwards
5236 compatible with Ada 83, Ada 83 programs may generally be compiled using
5237 this switch (see the description of the *-gnat83* switch for further
5238 information about Ada 83 mode).
5239 If an Ada 2005 program is compiled in Ada 95 mode,
5240 uses of the new Ada 2005 features will cause error
5241 messages or warnings.
5243 This switch also can be used to cancel the effect of a previous
5244 *-gnat83*, *-gnat05/2005*, or *-gnat12/2012*
5245 switch earlier in the command line.
5248 .. index:: -gnat05 (gcc)
5249 .. index:: -gnat2005 (gcc)
5250 .. index:: Ada 2005 mode
5252 :samp:`-gnat05` or :samp:`-gnat2005` (Ada 2005 mode)
5253 This switch directs the compiler to implement the Ada 2005 version of the
5254 language, as documented in the official Ada standards document.
5255 Since Ada 2005 is almost completely upwards
5256 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5257 may generally be compiled using this switch (see the description of the
5258 *-gnat83* and *-gnat95* switches for further
5262 .. index:: -gnat12 (gcc)
5263 .. index:: -gnat2012 (gcc)
5264 .. index:: Ada 2012 mode
5266 :samp:`-gnat12` or :samp:`-gnat2012` (Ada 2012 mode)
5267 This switch directs the compiler to implement the Ada 2012 version of the
5268 language (also the default).
5269 Since Ada 2012 is almost completely upwards
5270 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5271 Ada 83 and Ada 95 programs
5272 may generally be compiled using this switch (see the description of the
5273 *-gnat83*, *-gnat95*, and *-gnat05/2005* switches
5274 for further information).
5277 .. index:: -gnatX (gcc)
5278 .. index:: Ada language extensions
5279 .. index:: GNAT extensions
5281 :samp:`-gnatX` (Enable GNAT Extensions)
5282 This switch directs the compiler to implement the latest version of the
5283 language (currently Ada 2012) and also to enable certain GNAT implementation
5284 extensions that are not part of any Ada standard. For a full list of these
5285 extensions, see the GNAT reference manual.
5288 .. _Character_Set_Control:
5290 Character Set Control
5291 ---------------------
5293 .. index:: -gnati (gcc)
5296 Normally GNAT recognizes the Latin-1 character set in source program
5297 identifiers, as described in the Ada Reference Manual.
5299 GNAT to recognize alternate character sets in identifiers. `c` is a
5300 single character indicating the character set, as follows:
5302 ========== ======================================================
5303 *1* ISO 8859-1 (Latin-1) identifiers
5304 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5305 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5306 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5307 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5308 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5309 *p* IBM PC letters (code page 437) allowed in identifiers
5310 *8* IBM PC letters (code page 850) allowed in identifiers
5311 *f* Full upper-half codes allowed in identifiers
5312 *n* No upper-half codes allowed in identifiers
5313 *w* Wide-character codes (that is, codes greater than 255)
5314 allowed in identifiers
5315 ========== ======================================================
5317 See :ref:`Foreign_Language_Representation` for full details on the
5318 implementation of these character sets.
5321 .. index:: -gnatW (gcc)
5324 Specify the method of encoding for wide characters.
5325 `e` is one of the following:
5327 ========== ======================================================
5328 *h* Hex encoding (brackets coding also recognized)
5329 *u* Upper half encoding (brackets encoding also recognized)
5330 *s* Shift/JIS encoding (brackets encoding also recognized)
5331 *e* EUC encoding (brackets encoding also recognized)
5332 *8* UTF-8 encoding (brackets encoding also recognized)
5333 *b* Brackets encoding only (default value)
5334 ========== ======================================================
5336 For full details on these encoding
5337 methods see :ref:`Wide_Character_Encodings`.
5338 Note that brackets coding is always accepted, even if one of the other
5339 options is specified, so for example *-gnatW8* specifies that both
5340 brackets and UTF-8 encodings will be recognized. The units that are
5341 with'ed directly or indirectly will be scanned using the specified
5342 representation scheme, and so if one of the non-brackets scheme is
5343 used, it must be used consistently throughout the program. However,
5344 since brackets encoding is always recognized, it may be conveniently
5345 used in standard libraries, allowing these libraries to be used with
5346 any of the available coding schemes.
5348 Note that brackets encoding only applies to program text. Within comments,
5349 brackets are considered to be normal graphic characters, and bracket sequences
5350 are never recognized as wide characters.
5352 If no *-gnatW?* parameter is present, then the default
5353 representation is normally Brackets encoding only. However, if the
5354 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5355 byte order mark or BOM for UTF-8), then these three characters are
5356 skipped and the default representation for the file is set to UTF-8.
5358 Note that the wide character representation that is specified (explicitly
5359 or by default) for the main program also acts as the default encoding used
5360 for Wide_Text_IO files if not specifically overridden by a WCEM form
5364 When no *-gnatW?* is specified, then characters (other than wide
5365 characters represented using brackets notation) are treated as 8-bit
5366 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5367 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5368 characters in the range 16#00#..16#1F# are not accepted in program text
5369 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5370 in program text, but allowed and ignored in comments. Note in particular
5371 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5372 as an end of line in this default mode. If your source program contains
5373 instances of the NEL character used as a line terminator,
5374 you must use UTF-8 encoding for the whole
5375 source program. In default mode, all lines must be ended by a standard
5376 end of line sequence (CR, CR/LF, or LF).
5378 Note that the convention of simply accepting all upper half characters in
5379 comments means that programs that use standard ASCII for program text, but
5380 UTF-8 encoding for comments are accepted in default mode, providing that the
5381 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5382 This is a common mode for many programs with foreign language comments.
5384 .. _File_Naming_Control:
5389 .. index:: -gnatk (gcc)
5392 Activates file name 'krunching'. `n`, a decimal integer in the range
5393 1-999, indicates the maximum allowable length of a file name (not
5394 including the :file:`.ads` or :file:`.adb` extension). The default is not
5395 to enable file name krunching.
5397 For the source file naming rules, :ref:`File_Naming_Rules`.
5399 .. _Subprogram_Inlining_Control:
5401 Subprogram Inlining Control
5402 ---------------------------
5404 .. index:: -gnatn (gcc)
5407 The `n` here is intended to suggest the first syllable of the
5409 GNAT recognizes and processes `Inline` pragmas. However, for the
5410 inlining to actually occur, optimization must be enabled and, in order
5411 to enable inlining of subprograms specified by pragma `Inline`,
5412 you must also specify this switch.
5413 In the absence of this switch, GNAT does not attempt
5414 inlining and does not need to access the bodies of
5415 subprograms for which `pragma Inline` is specified if they are not
5416 in the current unit.
5418 You can optionally specify the inlining level: 1 for moderate inlining across
5419 modules, which is a good compromise between compilation times and performances
5420 at run time, or 2 for full inlining across modules, which may bring about
5421 longer compilation times. If no inlining level is specified, the compiler will
5422 pick it based on the optimization level: 1 for *-O1*, *-O2* or
5423 *-Os* and 2 for *-O3*.
5425 If you specify this switch the compiler will access these bodies,
5426 creating an extra source dependency for the resulting object file, and
5427 where possible, the call will be inlined.
5428 For further details on when inlining is possible
5429 see :ref:`Inlining_of_Subprograms`.
5432 .. index:: -gnatN (gcc)
5435 This switch activates front-end inlining which also
5436 generates additional dependencies.
5438 When using a gcc-based back end (in practice this means using any version
5439 of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
5440 *-gnatN* is deprecated, and the use of *-gnatn* is preferred.
5441 Historically front end inlining was more extensive than the gcc back end
5442 inlining, but that is no longer the case.
5444 .. _Auxiliary_Output_Control:
5446 Auxiliary Output Control
5447 ------------------------
5449 .. index:: -gnatt (gcc)
5450 .. index:: Writing internal trees
5451 .. index:: Internal trees, writing to file
5454 Causes GNAT to write the internal tree for a unit to a file (with the
5455 extension :file:`.adt`.
5456 This not normally required, but is used by separate analysis tools.
5458 these tools do the necessary compilations automatically, so you should
5459 not have to specify this switch in normal operation.
5460 Note that the combination of switches *-gnatct*
5461 generates a tree in the form required by ASIS applications.
5464 .. index:: -gnatu (gcc)
5467 Print a list of units required by this compilation on :file:`stdout`.
5468 The listing includes all units on which the unit being compiled depends
5469 either directly or indirectly.
5472 .. index:: -pass-exit-codes (gcc)
5474 :samp:`-pass-exit-codes`
5475 If this switch is not used, the exit code returned by *gcc* when
5476 compiling multiple files indicates whether all source files have
5477 been successfully used to generate object files or not.
5479 When *-pass-exit-codes* is used, *gcc* exits with an extended
5480 exit status and allows an integrated development environment to better
5481 react to a compilation failure. Those exit status are:
5483 ========== ======================================================
5484 *5* There was an error in at least one source file.
5485 *3* At least one source file did not generate an object file.
5486 *2* The compiler died unexpectedly (internal error for example).
5487 *0* An object file has been generated for every source file.
5488 ========== ======================================================
5490 .. _Debugging_Control:
5495 .. index:: Debugging options
5498 .. index:: -gnatd (gcc)
5501 Activate internal debugging switches. `x` is a letter or digit, or
5502 string of letters or digits, which specifies the type of debugging
5503 outputs desired. Normally these are used only for internal development
5504 or system debugging purposes. You can find full documentation for these
5505 switches in the body of the `Debug` unit in the compiler source
5506 file :file:`debug.adb`.
5509 .. index:: -gnatG (gcc)
5511 :samp:`-gnatG[={nn}]`
5512 This switch causes the compiler to generate auxiliary output containing
5513 a pseudo-source listing of the generated expanded code. Like most Ada
5514 compilers, GNAT works by first transforming the high level Ada code into
5515 lower level constructs. For example, tasking operations are transformed
5516 into calls to the tasking run-time routines. A unique capability of GNAT
5517 is to list this expanded code in a form very close to normal Ada source.
5518 This is very useful in understanding the implications of various Ada
5519 usage on the efficiency of the generated code. There are many cases in
5520 Ada (e.g., the use of controlled types), where simple Ada statements can
5521 generate a lot of run-time code. By using *-gnatG* you can identify
5522 these cases, and consider whether it may be desirable to modify the coding
5523 approach to improve efficiency.
5525 The optional parameter `nn` if present after -gnatG specifies an
5526 alternative maximum line length that overrides the normal default of 72.
5527 This value is in the range 40-999999, values less than 40 being silently
5528 reset to 40. The equal sign is optional.
5530 The format of the output is very similar to standard Ada source, and is
5531 easily understood by an Ada programmer. The following special syntactic
5532 additions correspond to low level features used in the generated code that
5533 do not have any exact analogies in pure Ada source form. The following
5534 is a partial list of these special constructions. See the spec
5535 of package `Sprint` in file :file:`sprint.ads` for a full list.
5537 .. index:: -gnatL (gcc)
5539 If the switch *-gnatL* is used in conjunction with
5540 *-gnatG*, then the original source lines are interspersed
5541 in the expanded source (as comment lines with the original line number).
5543 :samp:`new {xxx} [storage_pool = {yyy}]`
5544 Shows the storage pool being used for an allocator.
5547 :samp:`at end {procedure-name};`
5548 Shows the finalization (cleanup) procedure for a scope.
5551 :samp:`(if {expr} then {expr} else {expr})`
5552 Conditional expression equivalent to the `x?y:z` construction in C.
5555 :samp:`{target}^({source})`
5556 A conversion with floating-point truncation instead of rounding.
5559 :samp:`{target}?({source})`
5560 A conversion that bypasses normal Ada semantic checking. In particular
5561 enumeration types and fixed-point types are treated simply as integers.
5564 :samp:`{target}?^({source})`
5565 Combines the above two cases.
5570 :samp:`{x} #mod {y}`
5574 :samp:`{x} #rem {y}`
5575 A division or multiplication of fixed-point values which are treated as
5576 integers without any kind of scaling.
5579 :samp:`free {expr} [storage_pool = {xxx}]`
5580 Shows the storage pool associated with a `free` statement.
5583 :samp:`[subtype or type declaration]`
5584 Used to list an equivalent declaration for an internally generated
5585 type that is referenced elsewhere in the listing.
5588 :samp:`freeze {type-name} [{actions}]`
5589 Shows the point at which `type-name` is frozen, with possible
5590 associated actions to be performed at the freeze point.
5593 :samp:`reference {itype}`
5594 Reference (and hence definition) to internal type `itype`.
5597 :samp:`{function-name}! ({arg}, {arg}, {arg})`
5598 Intrinsic function call.
5601 :samp:`{label-name} : label`
5602 Declaration of label `labelname`.
5605 :samp:`#$ {subprogram-name}`
5606 An implicit call to a run-time support routine
5607 (to meet the requirement of H.3.1(9) in a
5611 :samp:`{expr} && {expr} && {expr} ... && {expr}`
5612 A multiple concatenation (same effect as `expr` & `expr` &
5613 `expr`, but handled more efficiently).
5616 :samp:`[constraint_error]`
5617 Raise the `Constraint_Error` exception.
5620 :samp:`{expression}'reference`
5621 A pointer to the result of evaluating {expression}.
5624 :samp:`{target-type}!({source-expression})`
5625 An unchecked conversion of `source-expression` to `target-type`.
5628 :samp:`[{numerator}/{denominator}]`
5629 Used to represent internal real literals (that) have no exact
5630 representation in base 2-16 (for example, the result of compile time
5631 evaluation of the expression 1.0/27.0).
5634 .. index:: -gnatD (gcc)
5637 When used in conjunction with *-gnatG*, this switch causes
5638 the expanded source, as described above for
5639 *-gnatG* to be written to files with names
5640 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
5641 instead of to the standard output file. For
5642 example, if the source file name is :file:`hello.adb`, then a file
5643 :file:`hello.adb.dg` will be written. The debugging
5644 information generated by the *gcc* *-g* switch
5645 will refer to the generated :file:`xxx.dg` file. This allows
5646 you to do source level debugging using the generated code which is
5647 sometimes useful for complex code, for example to find out exactly
5648 which part of a complex construction raised an exception. This switch
5649 also suppress generation of cross-reference information (see
5650 *-gnatx*) since otherwise the cross-reference information
5651 would refer to the :file:`.dg` file, which would cause
5652 confusion since this is not the original source file.
5654 Note that *-gnatD* actually implies *-gnatG*
5655 automatically, so it is not necessary to give both options.
5656 In other words *-gnatD* is equivalent to *-gnatDG*).
5658 .. index:: -gnatL (gcc)
5660 If the switch *-gnatL* is used in conjunction with
5661 *-gnatDG*, then the original source lines are interspersed
5662 in the expanded source (as comment lines with the original line number).
5664 The optional parameter `nn` if present after -gnatD specifies an
5665 alternative maximum line length that overrides the normal default of 72.
5666 This value is in the range 40-999999, values less than 40 being silently
5667 reset to 40. The equal sign is optional.
5670 .. index:: -gnatr (gcc)
5671 .. index:: pragma Restrictions
5674 This switch causes pragma Restrictions to be treated as Restriction_Warnings
5675 so that violation of restrictions causes warnings rather than illegalities.
5676 This is useful during the development process when new restrictions are added
5677 or investigated. The switch also causes pragma Profile to be treated as
5678 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
5679 restriction warnings rather than restrictions.
5682 .. index:: -gnatR (gcc)
5684 :samp:`-gnatR[0|1|2|3[s]]`
5685 This switch controls output from the compiler of a listing showing
5686 representation information for declared types and objects. For
5687 *-gnatR0*, no information is output (equivalent to omitting
5688 the *-gnatR* switch). For *-gnatR1* (which is the default,
5689 so *-gnatR* with no parameter has the same effect), size and alignment
5690 information is listed for declared array and record types. For
5691 *-gnatR2*, size and alignment information is listed for all
5692 declared types and objects. The `Linker_Section` is also listed for any
5693 entity for which the `Linker_Section` is set explicitly or implicitly (the
5694 latter case occurs for objects of a type for which a `Linker_Section`
5697 Finally *-gnatR3* includes symbolic
5698 expressions for values that are computed at run time for
5699 variant records. These symbolic expressions have a mostly obvious
5700 format with #n being used to represent the value of the n'th
5701 discriminant. See source files :file:`repinfo.ads/adb` in the
5702 `GNAT` sources for full details on the format of *-gnatR3*
5703 output. If the switch is followed by an s (e.g., *-gnatR2s*), then
5704 the output is to a file with the name :file:`file.rep` where
5705 file is the name of the corresponding source file.
5709 This form of the switch controls output of subprogram conventions
5710 and parameter passing mechanisms for all subprograms. A following
5711 `s` means output to a file as described above.
5713 Note that it is possible for record components to have zero size. In
5714 this case, the component clause uses an obvious extension of permitted
5715 Ada syntax, for example `at 0 range 0 .. -1`.
5717 Representation information requires that code be generated (since it is the
5718 code generator that lays out complex data structures). If an attempt is made
5719 to output representation information when no code is generated, for example
5720 when a subunit is compiled on its own, then no information can be generated
5721 and the compiler outputs a message to this effect.
5724 .. index:: -gnatS (gcc)
5727 The use of the switch *-gnatS* for an
5728 Ada compilation will cause the compiler to output a
5729 representation of package Standard in a form very
5730 close to standard Ada. It is not quite possible to
5731 do this entirely in standard Ada (since new
5732 numeric base types cannot be created in standard
5733 Ada), but the output is easily
5734 readable to any Ada programmer, and is useful to
5735 determine the characteristics of target dependent
5736 types in package Standard.
5739 .. index:: -gnatx (gcc)
5742 Normally the compiler generates full cross-referencing information in
5743 the :file:`ALI` file. This information is used by a number of tools,
5744 including `gnatfind` and `gnatxref`. The *-gnatx* switch
5745 suppresses this information. This saves some space and may slightly
5746 speed up compilation, but means that these tools cannot be used.
5748 .. _Exception_Handling_Control:
5750 Exception Handling Control
5751 --------------------------
5753 GNAT uses two methods for handling exceptions at run-time. The
5754 `setjmp/longjmp` method saves the context when entering
5755 a frame with an exception handler. Then when an exception is
5756 raised, the context can be restored immediately, without the
5757 need for tracing stack frames. This method provides very fast
5758 exception propagation, but introduces significant overhead for
5759 the use of exception handlers, even if no exception is raised.
5761 The other approach is called 'zero cost' exception handling.
5762 With this method, the compiler builds static tables to describe
5763 the exception ranges. No dynamic code is required when entering
5764 a frame containing an exception handler. When an exception is
5765 raised, the tables are used to control a back trace of the
5766 subprogram invocation stack to locate the required exception
5767 handler. This method has considerably poorer performance for
5768 the propagation of exceptions, but there is no overhead for
5769 exception handlers if no exception is raised. Note that in this
5770 mode and in the context of mixed Ada and C/C++ programming,
5771 to propagate an exception through a C/C++ code, the C/C++ code
5772 must be compiled with the *-funwind-tables* GCC's
5775 The following switches may be used to control which of the
5776 two exception handling methods is used.
5780 .. index:: --RTS=sjlj (gnatmake)
5783 This switch causes the setjmp/longjmp run-time (when available) to be used
5784 for exception handling. If the default
5785 mechanism for the target is zero cost exceptions, then
5786 this switch can be used to modify this default, and must be
5787 used for all units in the partition.
5788 This option is rarely used. One case in which it may be
5789 advantageous is if you have an application where exception
5790 raising is common and the overall performance of the
5791 application is improved by favoring exception propagation.
5794 .. index:: --RTS=zcx (gnatmake)
5795 .. index:: Zero Cost Exceptions
5798 This switch causes the zero cost approach to be used
5799 for exception handling. If this is the default mechanism for the
5800 target (see below), then this switch is unneeded. If the default
5801 mechanism for the target is setjmp/longjmp exceptions, then
5802 this switch can be used to modify this default, and must be
5803 used for all units in the partition.
5804 This option can only be used if the zero cost approach
5805 is available for the target in use, otherwise it will generate an error.
5807 The same option *--RTS* must be used both for *gcc*
5808 and *gnatbind*. Passing this option to *gnatmake*
5809 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
5810 through the compilation and binding steps.
5812 .. _Units_to_Sources_Mapping_Files:
5814 Units to Sources Mapping Files
5815 ------------------------------
5819 .. index:: -gnatem (gcc)
5821 :samp:`-gnatem={path}`
5822 A mapping file is a way to communicate to the compiler two mappings:
5823 from unit names to file names (without any directory information) and from
5824 file names to path names (with full directory information). These mappings
5825 are used by the compiler to short-circuit the path search.
5827 The use of mapping files is not required for correct operation of the
5828 compiler, but mapping files can improve efficiency, particularly when
5829 sources are read over a slow network connection. In normal operation,
5830 you need not be concerned with the format or use of mapping files,
5831 and the *-gnatem* switch is not a switch that you would use
5832 explicitly. It is intended primarily for use by automatic tools such as
5833 *gnatmake* running under the project file facility. The
5834 description here of the format of mapping files is provided
5835 for completeness and for possible use by other tools.
5837 A mapping file is a sequence of sets of three lines. In each set, the
5838 first line is the unit name, in lower case, with `%s` appended
5839 for specs and `%b` appended for bodies; the second line is the
5840 file name; and the third line is the path name.
5846 /gnat/project1/sources/main.2.ada
5849 When the switch *-gnatem* is specified, the compiler will
5850 create in memory the two mappings from the specified file. If there is
5851 any problem (nonexistent file, truncated file or duplicate entries),
5852 no mapping will be created.
5854 Several *-gnatem* switches may be specified; however, only the
5855 last one on the command line will be taken into account.
5857 When using a project file, *gnatmake* creates a temporary
5858 mapping file and communicates it to the compiler using this switch.
5861 .. _Code_Generation_Control:
5863 Code Generation Control
5864 -----------------------
5866 The GCC technology provides a wide range of target dependent
5867 :samp:`-m` switches for controlling
5868 details of code generation with respect to different versions of
5869 architectures. This includes variations in instruction sets (e.g.,
5870 different members of the power pc family), and different requirements
5871 for optimal arrangement of instructions (e.g., different members of
5872 the x86 family). The list of available *-m* switches may be
5873 found in the GCC documentation.
5875 Use of these *-m* switches may in some cases result in improved
5878 The GNAT technology is tested and qualified without any
5879 :samp:`-m` switches,
5880 so generally the most reliable approach is to avoid the use of these
5881 switches. However, we generally expect most of these switches to work
5882 successfully with GNAT, and many customers have reported successful
5883 use of these options.
5885 Our general advice is to avoid the use of *-m* switches unless
5886 special needs lead to requirements in this area. In particular,
5887 there is no point in using *-m* switches to improve performance
5888 unless you actually see a performance improvement.
5891 .. _Binding_with_gnatbind:
5893 Binding with `gnatbind`
5894 =======================
5896 .. index:: ! gnatbind
5898 This chapter describes the GNAT binder, `gnatbind`, which is used
5899 to bind compiled GNAT objects.
5901 Note: to invoke `gnatbind` with a project file, use the `gnat`
5902 driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
5904 The `gnatbind` program performs four separate functions:
5906 * Checks that a program is consistent, in accordance with the rules in
5907 Chapter 10 of the Ada Reference Manual. In particular, error
5908 messages are generated if a program uses inconsistent versions of a
5911 * Checks that an acceptable order of elaboration exists for the program
5912 and issues an error message if it cannot find an order of elaboration
5913 that satisfies the rules in Chapter 10 of the Ada Language Manual.
5915 * Generates a main program incorporating the given elaboration order.
5916 This program is a small Ada package (body and spec) that
5917 must be subsequently compiled
5918 using the GNAT compiler. The necessary compilation step is usually
5919 performed automatically by *gnatlink*. The two most important
5920 functions of this program
5921 are to call the elaboration routines of units in an appropriate order
5922 and to call the main program.
5924 * Determines the set of object files required by the given main program.
5925 This information is output in the forms of comments in the generated program,
5926 to be read by the *gnatlink* utility used to link the Ada application.
5928 .. _Running_gnatbind:
5933 The form of the `gnatbind` command is
5937 $ gnatbind [`switches`] `mainprog`[.ali] [`switches`]
5940 where :file:`mainprog.adb` is the Ada file containing the main program
5941 unit body. `gnatbind` constructs an Ada
5942 package in two files whose names are
5943 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
5944 For example, if given the
5945 parameter :file:`hello.ali`, for a main program contained in file
5946 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
5947 and :file:`b~hello.adb`.
5949 When doing consistency checking, the binder takes into consideration
5950 any source files it can locate. For example, if the binder determines
5951 that the given main program requires the package `Pack`, whose
5953 file is :file:`pack.ali` and whose corresponding source spec file is
5954 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
5955 (using the same search path conventions as previously described for the
5956 *gcc* command). If it can locate this source file, it checks that
5958 or source checksums of the source and its references to in :file:`ALI` files
5959 match. In other words, any :file:`ALI` files that mentions this spec must have
5960 resulted from compiling this version of the source file (or in the case
5961 where the source checksums match, a version close enough that the
5962 difference does not matter).
5964 .. index:: Source files, use by binder
5966 The effect of this consistency checking, which includes source files, is
5967 that the binder ensures that the program is consistent with the latest
5968 version of the source files that can be located at bind time. Editing a
5969 source file without compiling files that depend on the source file cause
5970 error messages to be generated by the binder.
5972 For example, suppose you have a main program :file:`hello.adb` and a
5973 package `P`, from file :file:`p.ads` and you perform the following
5976 * Enter `gcc -c hello.adb` to compile the main program.
5978 * Enter `gcc -c p.ads` to compile package `P`.
5980 * Edit file :file:`p.ads`.
5982 * Enter `gnatbind hello`.
5984 At this point, the file :file:`p.ali` contains an out-of-date time stamp
5985 because the file :file:`p.ads` has been edited. The attempt at binding
5986 fails, and the binder generates the following error messages:
5991 error: "hello.adb" must be recompiled ("p.ads" has been modified)
5992 error: "p.ads" has been modified and must be recompiled
5995 Now both files must be recompiled as indicated, and then the bind can
5996 succeed, generating a main program. You need not normally be concerned
5997 with the contents of this file, but for reference purposes a sample
5998 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6000 In most normal usage, the default mode of *gnatbind* which is to
6001 generate the main package in Ada, as described in the previous section.
6002 In particular, this means that any Ada programmer can read and understand
6003 the generated main program. It can also be debugged just like any other
6004 Ada code provided the *-g* switch is used for
6005 *gnatbind* and *gnatlink*.
6007 .. _Switches_for_gnatbind:
6009 Switches for *gnatbind*
6010 -----------------------
6012 The following switches are available with `gnatbind`; details will
6013 be presented in subsequent sections.
6016 .. index:: --version (gnatbind)
6019 Display Copyright and version, then exit disregarding all other options.
6022 .. index:: --help (gnatbind)
6025 If *--version* was not used, display usage, then exit disregarding
6029 .. index:: -a (gnatbind)
6032 Indicates that, if supported by the platform, the adainit procedure should
6033 be treated as an initialisation routine by the linker (a constructor). This
6034 is intended to be used by the Project Manager to automatically initialize
6035 shared Stand-Alone Libraries.
6038 .. index:: -aO (gnatbind)
6041 Specify directory to be searched for ALI files.
6044 .. index:: -aI (gnatbind)
6047 Specify directory to be searched for source file.
6050 .. index:: -A (gnatbind)
6052 :samp:`-A[={filename}]`
6053 Output ALI list (to standard output or to the named file).
6056 .. index:: -b (gnatbind)
6059 Generate brief messages to :file:`stderr` even if verbose mode set.
6062 .. index:: -c (gnatbind)
6065 Check only, no generation of binder output file.
6068 .. index:: -dnn[k|m] (gnatbind)
6071 This switch can be used to change the default task stack size value
6072 to a specified size `nn`, which is expressed in bytes by default, or
6073 in kilobytes when suffixed with `k` or in megabytes when suffixed
6075 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6076 in effect, to completing all task specs with
6080 pragma Storage_Size (nn);
6082 When they do not already have such a pragma.
6085 .. index:: -D (gnatbind)
6088 This switch can be used to change the default secondary stack size value
6089 to a specified size `nn`, which is expressed in bytes by default, or
6090 in kilobytes when suffixed with `k` or in megabytes when suffixed
6093 The secondary stack is used to deal with functions that return a variable
6094 sized result, for example a function returning an unconstrained
6095 String. There are two ways in which this secondary stack is allocated.
6097 For most targets, the secondary stack is growing on demand and is allocated
6098 as a chain of blocks in the heap. The -D option is not very
6099 relevant. It only give some control over the size of the allocated
6100 blocks (whose size is the minimum of the default secondary stack size value,
6101 and the actual size needed for the current allocation request).
6103 For certain targets, notably VxWorks 653,
6104 the secondary stack is allocated by carving off a fixed ratio chunk of the
6105 primary task stack. The -D option is used to define the
6106 size of the environment task's secondary stack.
6109 .. index:: -e (gnatbind)
6112 Output complete list of elaboration-order dependencies.
6115 .. index:: -Ea (gnatbind)
6118 Store tracebacks in exception occurrences when the target supports it.
6119 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6120 unless symbolic tracebacks are enabled.
6122 See also the packages `GNAT.Traceback` and
6123 `GNAT.Traceback.Symbolic` for more information.
6124 Note that on x86 ports, you must not use *-fomit-frame-pointer*
6128 .. index:: -Es (gnatbind)
6131 Store tracebacks in exception occurrences when the target supports it.
6132 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6135 .. index:: -E (gnatbind)
6138 Currently the same as `-Ea`.
6141 .. index:: -F (gnatbind)
6144 Force the checks of elaboration flags. *gnatbind* does not normally
6145 generate checks of elaboration flags for the main executable, except when
6146 a Stand-Alone Library is used. However, there are cases when this cannot be
6147 detected by gnatbind. An example is importing an interface of a Stand-Alone
6148 Library through a pragma Import and only specifying through a linker switch
6149 this Stand-Alone Library. This switch is used to guarantee that elaboration
6150 flag checks are generated.
6153 .. index:: -h (gnatbind)
6156 Output usage (help) information.
6159 .. index:: -H32 (gnatbind)
6162 Use 32-bit allocations for `__gnat_malloc` (and thus for access types).
6163 For further details see :ref:`Dynamic_Allocation_Control`.
6166 .. index:: -H64 (gnatbind)
6167 .. index:: __gnat_malloc
6170 Use 64-bit allocations for `__gnat_malloc` (and thus for access types).
6171 For further details see :ref:`Dynamic_Allocation_Control`.
6174 .. index:: -I (gnatbind)
6177 Specify directory to be searched for source and ALI files.
6180 .. index:: -I- (gnatbind)
6183 Do not look for sources in the current directory where `gnatbind` was
6184 invoked, and do not look for ALI files in the directory containing the
6185 ALI file named in the `gnatbind` command line.
6188 .. index:: -l (gnatbind)
6191 Output chosen elaboration order.
6194 .. index:: -L (gnatbind)
6197 Bind the units for library building. In this case the adainit and
6198 adafinal procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6199 are renamed to `xxx`init and
6202 (:ref:`GNAT_and_Libraries`, for more details.)
6205 .. index:: -M (gnatbind)
6208 Rename generated main program from main to xyz. This option is
6209 supported on cross environments only.
6212 .. index:: -m (gnatbind)
6215 Limit number of detected errors or warnings to `n`, where `n` is
6216 in the range 1..999999. The default value if no switch is
6217 given is 9999. If the number of warnings reaches this limit, then a
6218 message is output and further warnings are suppressed, the bind
6219 continues in this case. If the number of errors reaches this
6220 limit, then a message is output and the bind is abandoned.
6221 A value of zero means that no limit is enforced. The equal
6225 .. index:: -n (gnatbind)
6231 .. index:: -nostdinc (gnatbind)
6234 Do not look for sources in the system default directory.
6237 .. index:: -nostdlib (gnatbind)
6240 Do not look for library files in the system default directory.
6243 .. index:: --RTS (gnatbind)
6245 :samp:`--RTS={rts-path}`
6246 Specifies the default location of the runtime library. Same meaning as the
6247 equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
6249 .. index:: -o (gnatbind)
6252 Name the output file `file` (default is :file:`b~`xxx`.adb`).
6253 Note that if this option is used, then linking must be done manually,
6254 gnatlink cannot be used.
6257 .. index:: -O (gnatbind)
6259 :samp:`-O[={filename}]`
6260 Output object list (to standard output or to the named file).
6263 .. index:: -p (gnatbind)
6266 Pessimistic (worst-case) elaboration order.
6269 .. index:: -P (gnatbind)
6272 Generate binder file suitable for CodePeer.
6275 .. index:: -R (gnatbind)
6278 Output closure source list, which includes all non-run-time units that are
6279 included in the bind.
6282 .. index:: -Ra (gnatbind)
6285 Like *-R* but the list includes run-time units.
6288 .. index:: -s (gnatbind)
6291 Require all source files to be present.
6294 .. index:: -S (gnatbind)
6297 Specifies the value to be used when detecting uninitialized scalar
6298 objects with pragma Initialize_Scalars.
6299 The `xxx` string specified with the switch is one of:
6301 * ``in`` for an invalid value.
6303 If zero is invalid for the discrete type in question,
6304 then the scalar value is set to all zero bits.
6305 For signed discrete types, the largest possible negative value of
6306 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6307 For unsigned discrete types, the underlying scalar value is set to all
6308 one bits. For floating-point types, a NaN value is set
6309 (see body of package System.Scalar_Values for exact values).
6311 * ``lo`` for low value.
6313 If zero is invalid for the discrete type in question,
6314 then the scalar value is set to all zero bits.
6315 For signed discrete types, the largest possible negative value of
6316 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6317 For unsigned discrete types, the underlying scalar value is set to all
6318 zero bits. For floating-point, a small value is set
6319 (see body of package System.Scalar_Values for exact values).
6321 * ``hi`` for high value.
6323 If zero is invalid for the discrete type in question,
6324 then the scalar value is set to all one bits.
6325 For signed discrete types, the largest possible positive value of
6326 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6327 For unsigned discrete types, the underlying scalar value is set to all
6328 one bits. For floating-point, a large value is set
6329 (see body of package System.Scalar_Values for exact values).
6331 * `xx` for hex value (two hex digits).
6333 The underlying scalar is set to a value consisting of repeated bytes, whose
6334 value corresponds to the given value. For example if ``BF`` is given,
6335 then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``.
6337 .. index:: GNAT_INIT_SCALARS
6339 In addition, you can specify *-Sev* to indicate that the value is
6340 to be set at run time. In this case, the program will look for an environment
6341 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where `yy` is one
6342 of *in/lo/hi/`xx*` with the same meanings as above.
6343 If no environment variable is found, or if it does not have a valid value,
6344 then the default is *in* (invalid values).
6346 .. index:: -static (gnatbind)
6349 Link against a static GNAT run time.
6352 .. index:: -shared (gnatbind)
6355 Link against a shared GNAT run time when available.
6358 .. index:: -t (gnatbind)
6361 Tolerate time stamp and other consistency errors.
6364 .. index:: -T (gnatbind)
6367 Set the time slice value to `n` milliseconds. If the system supports
6368 the specification of a specific time slice value, then the indicated value
6369 is used. If the system does not support specific time slice values, but
6370 does support some general notion of round-robin scheduling, then any
6371 nonzero value will activate round-robin scheduling.
6373 A value of zero is treated specially. It turns off time
6374 slicing, and in addition, indicates to the tasking run time that the
6375 semantics should match as closely as possible the Annex D
6376 requirements of the Ada RM, and in particular sets the default
6377 scheduling policy to `FIFO_Within_Priorities`.
6380 .. index:: -u (gnatbind)
6383 Enable dynamic stack usage, with `n` results stored and displayed
6384 at program termination. A result is generated when a task
6385 terminates. Results that can't be stored are displayed on the fly, at
6386 task termination. This option is currently not supported on Itanium
6387 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6390 .. index:: -v (gnatbind)
6393 Verbose mode. Write error messages, header, summary output to
6397 .. index:: -V (gnatbind)
6399 :samp:`-V{key}={value}`
6400 Store the given association of `key` to `value` in the bind environment.
6401 Values stored this way can be retrieved at run time using
6402 `GNAT.Bind_Environment`.
6405 .. index:: -w (gnatbind)
6408 Warning mode; `x` = s/e for suppress/treat as error.
6411 .. index:: -Wx (gnatbind)
6414 Override default wide character encoding for standard Text_IO files.
6417 .. index:: -x (gnatbind)
6420 Exclude source files (check object consistency only).
6423 .. index:: -Xnnn (gnatbind)
6426 Set default exit status value, normally 0 for POSIX compliance.
6429 .. index:: -y (gnatbind)
6432 Enable leap seconds support in `Ada.Calendar` and its children.
6435 .. index:: -z (gnatbind)
6440 You may obtain this listing of switches by running `gnatbind` with
6444 .. _Consistency-Checking_Modes:
6446 Consistency-Checking Modes
6447 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6449 As described earlier, by default `gnatbind` checks
6450 that object files are consistent with one another and are consistent
6451 with any source files it can locate. The following switches control binder
6455 .. index:: -s (gnatbind)
6458 Require source files to be present. In this mode, the binder must be
6459 able to locate all source files that are referenced, in order to check
6460 their consistency. In normal mode, if a source file cannot be located it
6461 is simply ignored. If you specify this switch, a missing source
6465 .. index:: -Wx (gnatbind)
6468 Override default wide character encoding for standard Text_IO files.
6469 Normally the default wide character encoding method used for standard
6470 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6471 the main source input (see description of switch
6472 *-gnatWx* for the compiler). The
6473 use of this switch for the binder (which has the same set of
6474 possible arguments) overrides this default as specified.
6477 .. index:: -x (gnatbind)
6480 Exclude source files. In this mode, the binder only checks that ALI
6481 files are consistent with one another. Source files are not accessed.
6482 The binder runs faster in this mode, and there is still a guarantee that
6483 the resulting program is self-consistent.
6484 If a source file has been edited since it was last compiled, and you
6485 specify this switch, the binder will not detect that the object
6486 file is out of date with respect to the source file. Note that this is the
6487 mode that is automatically used by *gnatmake* because in this
6488 case the checking against sources has already been performed by
6489 *gnatmake* in the course of compilation (i.e., before binding).
6492 .. _Binder_Error_Message_Control:
6494 Binder Error Message Control
6495 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6497 The following switches provide control over the generation of error
6498 messages from the binder:
6502 .. index:: -v (gnatbind)
6505 Verbose mode. In the normal mode, brief error messages are generated to
6506 :file:`stderr`. If this switch is present, a header is written
6507 to :file:`stdout` and any error messages are directed to :file:`stdout`.
6508 All that is written to :file:`stderr` is a brief summary message.
6511 .. index:: -b (gnatbind)
6514 Generate brief error messages to :file:`stderr` even if verbose mode is
6515 specified. This is relevant only when used with the
6519 .. index:: -m (gnatbind)
6522 Limits the number of error messages to `n`, a decimal integer in the
6523 range 1-999. The binder terminates immediately if this limit is reached.
6526 .. index:: -M (gnatbind)
6529 Renames the generated main program from `main` to `xxx`.
6530 This is useful in the case of some cross-building environments, where
6531 the actual main program is separate from the one generated
6535 .. index:: -ws (gnatbind)
6539 Suppress all warning messages.
6542 .. index:: -we (gnatbind)
6545 Treat any warning messages as fatal errors.
6548 .. index:: -t (gnatbind)
6549 .. index:: Time stamp checks, in binder
6550 .. index:: Binder consistency checks
6551 .. index:: Consistency checks, in binder
6554 The binder performs a number of consistency checks including:
6557 * Check that time stamps of a given source unit are consistent
6559 * Check that checksums of a given source unit are consistent
6561 * Check that consistent versions of `GNAT` were used for compilation
6563 * Check consistency of configuration pragmas as required
6565 Normally failure of such checks, in accordance with the consistency
6566 requirements of the Ada Reference Manual, causes error messages to be
6567 generated which abort the binder and prevent the output of a binder
6568 file and subsequent link to obtain an executable.
6570 The *-t* switch converts these error messages
6571 into warnings, so that
6572 binding and linking can continue to completion even in the presence of such
6573 errors. The result may be a failed link (due to missing symbols), or a
6574 non-functional executable which has undefined semantics.
6578 This means that *-t* should be used only in unusual situations,
6581 .. _Elaboration_Control:
6586 The following switches provide additional control over the elaboration
6587 order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`.
6590 .. index:: -p (gnatbind)
6593 Normally the binder attempts to choose an elaboration order that is
6594 likely to minimize the likelihood of an elaboration order error resulting
6595 in raising a `Program_Error` exception. This switch reverses the
6596 action of the binder, and requests that it deliberately choose an order
6597 that is likely to maximize the likelihood of an elaboration error.
6598 This is useful in ensuring portability and avoiding dependence on
6599 accidental fortuitous elaboration ordering.
6601 Normally it only makes sense to use the *-p*
6603 elaboration checking is used (*-gnatE* switch used for compilation).
6604 This is because in the default static elaboration mode, all necessary
6605 `Elaborate` and `Elaborate_All` pragmas are implicitly inserted.
6606 These implicit pragmas are still respected by the binder in
6608 safe elaboration order is assured.
6610 Note that *-p* is not intended for
6611 production use; it is more for debugging/experimental use.
6618 The following switches allow additional control over the output
6619 generated by the binder.
6622 .. index:: -c (gnatbind)
6625 Check only. Do not generate the binder output file. In this mode the
6626 binder performs all error checks but does not generate an output file.
6629 .. index:: -e (gnatbind)
6632 Output complete list of elaboration-order dependencies, showing the
6633 reason for each dependency. This output can be rather extensive but may
6634 be useful in diagnosing problems with elaboration order. The output is
6635 written to :file:`stdout`.
6638 .. index:: -h (gnatbind)
6641 Output usage information. The output is written to :file:`stdout`.
6644 .. index:: -K (gnatbind)
6647 Output linker options to :file:`stdout`. Includes library search paths,
6648 contents of pragmas Ident and Linker_Options, and libraries added
6652 .. index:: -l (gnatbind)
6655 Output chosen elaboration order. The output is written to :file:`stdout`.
6658 .. index:: -O (gnatbind)
6661 Output full names of all the object files that must be linked to provide
6662 the Ada component of the program. The output is written to :file:`stdout`.
6663 This list includes the files explicitly supplied and referenced by the user
6664 as well as implicitly referenced run-time unit files. The latter are
6665 omitted if the corresponding units reside in shared libraries. The
6666 directory names for the run-time units depend on the system configuration.
6669 .. index:: -o (gnatbind)
6672 Set name of output file to `file` instead of the normal
6673 :file:`b~`mainprog`.adb` default. Note that `file` denote the Ada
6674 binder generated body filename.
6675 Note that if this option is used, then linking must be done manually.
6676 It is not possible to use gnatlink in this case, since it cannot locate
6680 .. index:: -r (gnatbind)
6683 Generate list of `pragma Restrictions` that could be applied to
6684 the current unit. This is useful for code audit purposes, and also may
6685 be used to improve code generation in some cases.
6688 .. _Dynamic_Allocation_Control:
6690 Dynamic Allocation Control
6691 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6693 The heap control switches -- *-H32* and *-H64* --
6694 determine whether dynamic allocation uses 32-bit or 64-bit memory.
6695 They only affect compiler-generated allocations via `__gnat_malloc`;
6696 explicit calls to `malloc` and related functions from the C
6697 run-time library are unaffected.
6700 Allocate memory on 32-bit heap
6704 Allocate memory on 64-bit heap. This is the default
6705 unless explicitly overridden by a `'Size` clause on the access type.
6707 These switches are only effective on VMS platforms.
6710 .. _Binding_with_Non-Ada_Main_Programs:
6712 Binding with Non-Ada Main Programs
6713 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6715 The description so far has assumed that the main
6716 program is in Ada, and that the task of the binder is to generate a
6717 corresponding function `main` that invokes this Ada main
6718 program. GNAT also supports the building of executable programs where
6719 the main program is not in Ada, but some of the called routines are
6720 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
6721 The following switch is used in this situation:
6724 .. index:: -n (gnatbind)
6727 No main program. The main program is not in Ada.
6729 In this case, most of the functions of the binder are still required,
6730 but instead of generating a main program, the binder generates a file
6731 containing the following callable routines:
6736 You must call this routine to initialize the Ada part of the program by
6737 calling the necessary elaboration routines. A call to `adainit` is
6738 required before the first call to an Ada subprogram.
6740 Note that it is assumed that the basic execution environment must be setup
6741 to be appropriate for Ada execution at the point where the first Ada
6742 subprogram is called. In particular, if the Ada code will do any
6743 floating-point operations, then the FPU must be setup in an appropriate
6744 manner. For the case of the x86, for example, full precision mode is
6745 required. The procedure GNAT.Float_Control.Reset may be used to ensure
6746 that the FPU is in the right state.
6751 You must call this routine to perform any library-level finalization
6752 required by the Ada subprograms. A call to `adafinal` is required
6753 after the last call to an Ada subprogram, and before the program
6756 .. index:: -n (gnatbind)
6757 .. index:: Binder, multiple input files
6760 is given, more than one ALI file may appear on
6761 the command line for `gnatbind`. The normal *closure*
6762 calculation is performed for each of the specified units. Calculating
6763 the closure means finding out the set of units involved by tracing
6764 |with| references. The reason it is necessary to be able to
6765 specify more than one ALI file is that a given program may invoke two or
6766 more quite separate groups of Ada units.
6768 The binder takes the name of its output file from the last specified ALI
6769 file, unless overridden by the use of the *-o file*.
6771 .. index:: -o (gnatbind)
6773 The output is an Ada unit in source form that can be compiled with GNAT.
6774 This compilation occurs automatically as part of the *gnatlink*
6777 Currently the GNAT run time requires a FPU using 80 bits mode
6778 precision. Under targets where this is not the default it is required to
6779 call GNAT.Float_Control.Reset before using floating point numbers (this
6780 include float computation, float input and output) in the Ada code. A
6781 side effect is that this could be the wrong mode for the foreign code
6782 where floating point computation could be broken after this call.
6785 .. _Binding_Programs_with_No_Main_Subprogram:
6787 Binding Programs with No Main Subprogram
6788 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6790 It is possible to have an Ada program which does not have a main
6791 subprogram. This program will call the elaboration routines of all the
6792 packages, then the finalization routines.
6794 The following switch is used to bind programs organized in this manner:
6796 .. index:: -z (gnatbind)
6799 Normally the binder checks that the unit name given on the command line
6800 corresponds to a suitable main subprogram. When this switch is used,
6801 a list of ALI files can be given, and the execution of the program
6802 consists of elaboration of these units in an appropriate order. Note
6803 that the default wide character encoding method for standard Text_IO
6804 files is always set to Brackets if this switch is set (you can use
6806 *-Wx* to override this default).
6809 .. _Command-Line_Access:
6814 The package `Ada.Command_Line` provides access to the command-line
6815 arguments and program name. In order for this interface to operate
6816 correctly, the two variables
6823 .. index:: gnat_argv
6824 .. index:: gnat_argc
6826 are declared in one of the GNAT library routines. These variables must
6827 be set from the actual `argc` and `argv` values passed to the
6828 main program. With no *n* present, `gnatbind`
6829 generates the C main program to automatically set these variables.
6830 If the *n* switch is used, there is no automatic way to
6831 set these variables. If they are not set, the procedures in
6832 `Ada.Command_Line` will not be available, and any attempt to use
6833 them will raise `Constraint_Error`. If command line access is
6834 required, your main program must set `gnat_argc` and
6835 `gnat_argv` from the `argc` and `argv` values passed to
6839 .. _Search_Paths_for_gnatbind:
6841 Search Paths for `gnatbind`
6842 ---------------------------
6844 The binder takes the name of an ALI file as its argument and needs to
6845 locate source files as well as other ALI files to verify object consistency.
6847 For source files, it follows exactly the same search rules as *gcc*
6848 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
6849 directories searched are:
6851 * The directory containing the ALI file named in the command line, unless
6852 the switch *-I-* is specified.
6854 * All directories specified by *-I*
6855 switches on the `gnatbind`
6856 command line, in the order given.
6858 .. index:: ADA_PRJ_OBJECTS_FILE
6860 * Each of the directories listed in the text file whose name is given
6861 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
6863 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
6864 driver when project files are used. It should not normally be set
6867 .. index:: ADA_OBJECTS_PATH
6869 * Each of the directories listed in the value of the
6870 :envvar:`ADA_OBJECTS_PATH` environment variable.
6871 Construct this value
6872 exactly as the :envvar:`PATH` environment variable: a list of directory
6873 names separated by colons (semicolons when working with the NT version
6876 * The content of the :file:`ada_object_path` file which is part of the GNAT
6877 installation tree and is used to store standard libraries such as the
6878 GNAT Run Time Library (RTL) unless the switch *-nostdlib* is
6879 specified. See :ref:`Installing_a_library`
6881 .. index:: -I (gnatbind)
6882 .. index:: -aI (gnatbind)
6883 .. index:: -aO (gnatbind)
6885 In the binder the switch *-I*
6886 is used to specify both source and
6887 library file paths. Use *-aI*
6888 instead if you want to specify
6889 source paths only, and *-aO*
6890 if you want to specify library paths
6891 only. This means that for the binder
6892 :samp:`-I{dir}` is equivalent to
6895 The binder generates the bind file (a C language source file) in the
6896 current working directory.
6900 .. index:: Interfaces
6903 The packages `Ada`, `System`, and `Interfaces` and their
6904 children make up the GNAT Run-Time Library, together with the package
6905 GNAT and its children, which contain a set of useful additional
6906 library functions provided by GNAT. The sources for these units are
6907 needed by the compiler and are kept together in one directory. The ALI
6908 files and object files generated by compiling the RTL are needed by the
6909 binder and the linker and are kept together in one directory, typically
6910 different from the directory containing the sources. In a normal
6911 installation, you need not specify these directory names when compiling
6912 or binding. Either the environment variables or the built-in defaults
6913 cause these files to be found.
6915 Besides simplifying access to the RTL, a major use of search paths is
6916 in compiling sources from multiple directories. This can make
6917 development environments much more flexible.
6920 .. _Examples_of_gnatbind_Usage:
6922 Examples of `gnatbind` Usage
6923 ----------------------------
6925 Here are some examples of `gnatbind` invovations:
6931 The main program `Hello` (source program in :file:`hello.adb`) is
6932 bound using the standard switch settings. The generated main program is
6933 :file:`b~hello.adb`. This is the normal, default use of the binder.
6937 gnatbind hello -o mainprog.adb
6939 The main program `Hello` (source program in :file:`hello.adb`) is
6940 bound using the standard switch settings. The generated main program is
6941 :file:`mainprog.adb` with the associated spec in
6942 :file:`mainprog.ads`. Note that you must specify the body here not the
6943 spec. Note that if this option is used, then linking must be done manually,
6944 since gnatlink will not be able to find the generated file.
6947 .. _Linking_with_gnatlink:
6949 Linking with *gnatlink*
6950 =======================
6952 .. index:: ! gnatlink
6954 This chapter discusses *gnatlink*, a tool that links
6955 an Ada program and builds an executable file. This utility
6956 invokes the system linker (via the *gcc* command)
6957 with a correct list of object files and library references.
6958 *gnatlink* automatically determines the list of files and
6959 references for the Ada part of a program. It uses the binder file
6960 generated by the *gnatbind* to determine this list.
6962 Note: to invoke `gnatlink` with a project file, use the `gnat`
6963 driver (see :ref:`The_GNAT_Driver_and_Project_Files`).
6965 .. _Running_gnatlink:
6970 The form of the *gnatlink* command is
6975 $ gnatlink [`switches`] `mainprog`[.ali]
6976 [`non-Ada objects`] [`linker options`]
6980 The arguments of *gnatlink* (switches, main :file:`ALI` file,
6982 or linker options) may be in any order, provided that no non-Ada object may
6983 be mistaken for a main :file:`ALI` file.
6984 Any file name :file:`F` without the :file:`.ali`
6985 extension will be taken as the main :file:`ALI` file if a file exists
6986 whose name is the concatenation of :file:`F` and :file:`.ali`.
6988 :file:`mainprog.ali` references the ALI file of the main program.
6989 The :file:`.ali` extension of this file can be omitted. From this
6990 reference, *gnatlink* locates the corresponding binder file
6991 :file:`b~mainprog.adb` and, using the information in this file along
6992 with the list of non-Ada objects and linker options, constructs a
6993 linker command file to create the executable.
6995 The arguments other than the *gnatlink* switches and the main
6996 :file:`ALI` file are passed to the linker uninterpreted.
6997 They typically include the names of
6998 object files for units written in other languages than Ada and any library
6999 references required to resolve references in any of these foreign language
7000 units, or in `Import` pragmas in any Ada units.
7002 `linker options` is an optional list of linker specific
7004 The default linker called by gnatlink is *gcc* which in
7005 turn calls the appropriate system linker.
7007 One useful option for the linker is *-s*: it reduces the size of the
7008 executable by removing all symbol table and relocation information from the
7011 Standard options for the linker such as *-lmy_lib* or
7012 *-Ldir* can be added as is.
7013 For options that are not recognized by
7014 *gcc* as linker options, use the *gcc* switches
7015 *-Xlinker* or *-Wl,*.
7017 Refer to the GCC documentation for
7020 Here is an example showing how to generate a linker map:
7024 $ gnatlink my_prog -Wl,-Map,MAPFILE
7027 Using `linker options` it is possible to set the program stack and
7029 See :ref:`Setting_Stack_Size_from_gnatlink` and
7030 :ref:`Setting_Heap_Size_from_gnatlink`.
7032 *gnatlink* determines the list of objects required by the Ada
7033 program and prepends them to the list of objects passed to the linker.
7034 *gnatlink* also gathers any arguments set by the use of
7035 `pragma Linker_Options` and adds them to the list of arguments
7036 presented to the linker.
7039 .. _Switches_for_gnatlink:
7041 Switches for *gnatlink*
7042 -----------------------
7044 The following switches are available with the *gnatlink* utility:
7046 .. index:: --version (gnatlink)
7049 Display Copyright and version, then exit disregarding all other options.
7052 .. index:: --help (gnatlink)
7055 If *--version* was not used, display usage, then exit disregarding
7059 .. index:: Command line length
7060 .. index:: -f (gnatlink)
7063 On some targets, the command line length is limited, and *gnatlink*
7064 will generate a separate file for the linker if the list of object files
7066 The *-f* switch forces this file
7067 to be generated even if
7068 the limit is not exceeded. This is useful in some cases to deal with
7069 special situations where the command line length is exceeded.
7072 .. index:: Debugging information, including
7073 .. index:: -g (gnatlink)
7076 The option to include debugging information causes the Ada bind file (in
7077 other words, :file:`b~mainprog.adb`) to be compiled with *-g*.
7078 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7079 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7080 Without *-g*, the binder removes these files by default.
7082 .. index:: -n (gnatlink)
7085 Do not compile the file generated by the binder. This may be used when
7086 a link is rerun with different options, but there is no need to recompile
7090 .. index:: -v (gnatlink)
7093 Verbose mode. Causes additional information to be output, including a full
7094 list of the included object files.
7095 This switch option is most useful when you want
7096 to see what set of object files are being used in the link step.
7099 .. index:: -v -v (gnatlink)
7102 Very verbose mode. Requests that the compiler operate in verbose mode when
7103 it compiles the binder file, and that the system linker run in verbose mode.
7106 .. index:: -o (gnatlink)
7108 :samp:`-o {exec-name}`
7109 `exec-name` specifies an alternate name for the generated
7110 executable program. If this switch is omitted, the executable has the same
7111 name as the main unit. For example, `gnatlink try.ali` creates
7112 an executable called :file:`try`.
7115 .. index:: -b (gnatlink)
7118 Compile your program to run on `target`, which is the name of a
7119 system configuration. You must have a GNAT cross-compiler built if
7120 `target` is not the same as your host system.
7123 .. index:: -B (gnatlink)
7126 Load compiler executables (for example, `gnat1`, the Ada compiler)
7127 from `dir` instead of the default location. Only use this switch
7128 when multiple versions of the GNAT compiler are available.
7129 See the `Directory Options` section in :title:`The_GNU_Compiler_Collection`
7130 for further details. You would normally use the *-b* or
7131 *-V* switch instead.
7134 .. index:: -M (gnatlink)
7137 When linking an executable, create a map file. The name of the map file
7138 has the same name as the executable with extension ".map".
7141 .. index:: -M= (gnatlink)
7143 :samp:`-M={mapfile}`
7144 When linking an executable, create a map file. The name of the map file is
7148 .. index:: --GCC=compiler_name (gnatlink)
7150 :samp:`--GCC={compiler_name}`
7151 Program used for compiling the binder file. The default is
7152 ``gcc``. You need to use quotes around `compiler_name` if
7153 `compiler_name` contains spaces or other separator characters.
7154 As an example ``--GCC="foo -x -y"`` will instruct *gnatlink* to
7155 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7156 inserted after your command name. Thus in the above example the compiler
7157 command that will be used by *gnatlink* will be ``foo -c -x -y``.
7158 A limitation of this syntax is that the name and path name of the executable
7159 itself must not include any embedded spaces. If the compiler executable is
7160 different from the default one (gcc or <prefix>-gcc), then the back-end
7161 switches in the ALI file are not used to compile the binder generated source.
7162 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7163 switches will be used for ``--GCC="gcc -gnatv"``. If several
7164 ``--GCC=compiler_name`` are used, only the last `compiler_name`
7165 is taken into account. However, all the additional switches are also taken
7167 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7168 ``--GCC="bar -x -y -z -t"``.
7171 .. index:: --LINK= (gnatlink)
7173 :samp:`--LINK={name}`
7174 `name` is the name of the linker to be invoked. This is especially
7175 useful in mixed language programs since languages such as C++ require
7176 their own linker to be used. When this switch is omitted, the default
7177 name for the linker is *gcc*. When this switch is used, the
7178 specified linker is called instead of *gcc* with exactly the same
7179 parameters that would have been passed to *gcc* so if the desired
7180 linker requires different parameters it is necessary to use a wrapper
7181 script that massages the parameters before invoking the real linker. It
7182 may be useful to control the exact invocation by using the verbose
7186 .. _Using_the_GNU_make_Utility:
7188 Using the GNU `make` Utility
7189 ============================
7191 .. index:: make (GNU), GNU make
7193 This chapter offers some examples of makefiles that solve specific
7194 problems. It does not explain how to write a makefile, nor does it try to replace the
7195 *gnatmake* utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7197 All the examples in this section are specific to the GNU version of
7198 make. Although *make* is a standard utility, and the basic language
7199 is the same, these examples use some advanced features found only in
7202 .. _Using_gnatmake_in_a_Makefile:
7204 Using gnatmake in a Makefile
7205 ----------------------------
7207 .. index makefile (GNU make)
7209 Complex project organizations can be handled in a very powerful way by
7210 using GNU make combined with gnatmake. For instance, here is a Makefile
7211 which allows you to build each subsystem of a big project into a separate
7212 shared library. Such a makefile allows you to significantly reduce the link
7213 time of very big applications while maintaining full coherence at
7214 each step of the build process.
7216 The list of dependencies are handled automatically by
7217 *gnatmake*. The Makefile is simply used to call gnatmake in each of
7218 the appropriate directories.
7220 Note that you should also read the example on how to automatically
7221 create the list of directories
7222 (:ref:`Automatically_Creating_a_List_of_Directories`)
7223 which might help you in case your project has a lot of subdirectories.
7226 .. code-block:: makefile
7228 ## This Makefile is intended to be used with the following directory
7230 ## - The sources are split into a series of csc (computer software components)
7231 ## Each of these csc is put in its own directory.
7232 ## Their name are referenced by the directory names.
7233 ## They will be compiled into shared library (although this would also work
7234 ## with static libraries
7235 ## - The main program (and possibly other packages that do not belong to any
7236 ## csc is put in the top level directory (where the Makefile is).
7237 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7238 ## \\_ second_csc (sources) __ lib (will contain the library)
7240 ## Although this Makefile is build for shared library, it is easy to modify
7241 ## to build partial link objects instead (modify the lines with -shared and
7244 ## With this makefile, you can change any file in the system or add any new
7245 ## file, and everything will be recompiled correctly (only the relevant shared
7246 ## objects will be recompiled, and the main program will be re-linked).
7248 # The list of computer software component for your project. This might be
7249 # generated automatically.
7252 # Name of the main program (no extension)
7255 # If we need to build objects with -fPIC, uncomment the following line
7258 # The following variable should give the directory containing libgnat.so
7259 # You can get this directory through 'gnatls -v'. This is usually the last
7260 # directory in the Object_Path.
7263 # The directories for the libraries
7264 # (This macro expands the list of CSC to the list of shared libraries, you
7265 # could simply use the expanded form:
7266 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7267 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7269 ${MAIN}: objects ${LIB_DIR}
7270 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7271 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7274 # recompile the sources
7275 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7277 # Note: In a future version of GNAT, the following commands will be simplified
7278 # by a new tool, gnatmlib
7281 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7282 cd ${dir $@ } && cp -f ../*.ali .
7284 # The dependencies for the modules
7285 # Note that we have to force the expansion of *.o, since in some cases
7286 # make won't be able to do it itself.
7287 aa/lib/libaa.so: ${wildcard aa/*.o}
7288 bb/lib/libbb.so: ${wildcard bb/*.o}
7289 cc/lib/libcc.so: ${wildcard cc/*.o}
7291 # Make sure all of the shared libraries are in the path before starting the
7294 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7297 ${RM} -rf ${CSC_LIST:%=%/lib}
7298 ${RM} ${CSC_LIST:%=%/*.ali}
7299 ${RM} ${CSC_LIST:%=%/*.o}
7300 ${RM} *.o *.ali ${MAIN}
7303 .. _Automatically_Creating_a_List_of_Directories:
7305 Automatically Creating a List of Directories
7306 --------------------------------------------
7308 In most makefiles, you will have to specify a list of directories, and
7309 store it in a variable. For small projects, it is often easier to
7310 specify each of them by hand, since you then have full control over what
7311 is the proper order for these directories, which ones should be
7314 However, in larger projects, which might involve hundreds of
7315 subdirectories, it might be more convenient to generate this list
7318 The example below presents two methods. The first one, although less
7319 general, gives you more control over the list. It involves wildcard
7320 characters, that are automatically expanded by *make*. Its
7321 shortcoming is that you need to explicitly specify some of the
7322 organization of your project, such as for instance the directory tree
7323 depth, whether some directories are found in a separate tree, etc.
7325 The second method is the most general one. It requires an external
7326 program, called *find*, which is standard on all Unix systems. All
7327 the directories found under a given root directory will be added to the
7330 .. code-block:: makefile
7332 # The examples below are based on the following directory hierarchy:
7333 # All the directories can contain any number of files
7334 # ROOT_DIRECTORY -> a -> aa -> aaa
7340 # This Makefile creates a variable called DIRS, that can be reused any time
7341 # you need this list (see the other examples in this section)
7343 # The root of your project's directory hierarchy
7347 # First method: specify explicitly the list of directories
7348 # This allows you to specify any subset of all the directories you need.
7351 DIRS := a/aa/ a/ab/ b/ba/
7354 # Second method: use wildcards
7355 # Note that the argument(s) to wildcard below should end with a '/'.
7356 # Since wildcards also return file names, we have to filter them out
7357 # to avoid duplicate directory names.
7358 # We thus use make's `dir` and `sort` functions.
7359 # It sets DIRs to the following value (note that the directories aaa and baa
7360 # are not given, unless you change the arguments to wildcard).
7361 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7364 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7365 ${ROOT_DIRECTORY}/*/*/}}}
7368 # Third method: use an external program
7369 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7370 # This is the most complete command: it sets DIRs to the following value:
7371 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7374 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7378 .. _Generating_the_Command_Line_Switches:
7380 Generating the Command Line Switches
7381 ------------------------------------
7383 Once you have created the list of directories as explained in the
7384 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7385 you can easily generate the command line arguments to pass to gnatmake.
7387 For the sake of completeness, this example assumes that the source path
7388 is not the same as the object path, and that you have two separate lists
7391 .. code-block:: makefile
7393 # see "Automatically creating a list of directories" to create
7398 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7399 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7402 gnatmake ${GNATMAKE_SWITCHES} main_unit
7405 .. _Overcoming_Command_Line_Length_Limits:
7407 Overcoming Command Line Length Limits
7408 -------------------------------------
7410 One problem that might be encountered on big projects is that many
7411 operating systems limit the length of the command line. It is thus hard to give
7412 gnatmake the list of source and object directories.
7414 This example shows how you can set up environment variables, which will
7415 make *gnatmake* behave exactly as if the directories had been
7416 specified on the command line, but have a much higher length limit (or
7417 even none on most systems).
7419 It assumes that you have created a list of directories in your Makefile,
7420 using one of the methods presented in
7421 :ref:`Automatically_Creating_a_List_of_Directories`.
7422 For the sake of completeness, we assume that the object
7423 path (where the ALI files are found) is different from the sources patch.
7425 Note a small trick in the Makefile below: for efficiency reasons, we
7426 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7427 expanded immediately by `make`. This way we overcome the standard
7428 make behavior which is to expand the variables only when they are
7431 On Windows, if you are using the standard Windows command shell, you must
7432 replace colons with semicolons in the assignments to these variables.
7434 .. code-block:: makefile
7436 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7437 # This is the same thing as putting the -I arguments on the command line.
7438 # (the equivalent of using -aI on the command line would be to define
7439 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
7440 # You can of course have different values for these variables.
7442 # Note also that we need to keep the previous values of these variables, since
7443 # they might have been set before running 'make' to specify where the GNAT
7444 # library is installed.
7446 # see "Automatically creating a list of directories" to create these
7452 space:=${empty} ${empty}
7453 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
7454 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
7455 ADA_INCLUDE_PATH += ${SOURCE_LIST}
7456 ADA_OBJECTS_PATH += ${OBJECT_LIST}
7457 export ADA_INCLUDE_PATH
7458 export ADA_OBJECTS_PATH