Debian Codegraph @

gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst

raw
1 .. |with| replace:: *with*
2 .. |withs| replace:: *with*\ s
3 .. |withed| replace:: *with*\ ed
4 .. |withing| replace:: *with*\ ing
5
6 .. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
7
8 .. role:: switch(samp)
9
10 .. _Building_Executable_Programs_With_GNAT:
11
12 **************************************
13 Building Executable Programs with GNAT
14 **************************************
15
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`).
29
30 .. only:: PRO or GPL
31
32 For building large systems with components possibly written
33 in different languages (such as Ada, C, C++ and Fortran)
34 and organized into subsystems and libraries, the GPRbuild
35 tool can be used. This tool, and the Project Manager
36 facility that it is based upon, is described in
37 *GPRbuild and GPR Companion Tools User's Guide*.
38
39
40 .. _The_GNAT_Make_Program_gnatmake:
41
42 Building with ``gnatmake``
43 ==========================
44
45 .. index:: gnatmake
46
47 A typical development cycle when working on an Ada program consists of
48 the following steps:
49
50 #. Edit some sources to fix bugs;
51
52 #. Add enhancements;
53
54 #. Compile all sources affected;
55
56 #. Rebind and relink; and
57
58 #. Test.
59
60 .. index:: Dependency rules (compilation)
61
62 The third step in particular can be tricky, because not only do the modified
63 files have to be compiled, but any files depending on these files must also be
64 recompiled. The dependency rules in Ada can be quite complex, especially
65 in the presence of overloading, ``use`` clauses, generics and inlined
66 subprograms.
67
68 ``gnatmake`` automatically takes care of the third and fourth steps
69 of this process. It determines which sources need to be compiled,
70 compiles them, and binds and links the resulting object files.
71
72 Unlike some other Ada make programs, the dependencies are always
73 accurately recomputed from the new sources. The source based approach of
74 the GNAT compilation model makes this possible. This means that if
75 changes to the source program cause corresponding changes in
76 dependencies, they will always be tracked exactly correctly by
77 ``gnatmake``.
78
79 Note that for advanced forms of project structure, we recommend creating
80 a project file as explained in the *GNAT_Project_Manager* chapter in the
81 *GPRbuild User's Guide*, and using the
82 ``gprbuild`` tool which supports building with project files and works similarly
83 to ``gnatmake``.
84
85 .. _Running_gnatmake:
86
87 Running ``gnatmake``
88 --------------------
89
90 The usual form of the ``gnatmake`` command is
91
92 .. code-block:: sh
93
94 $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
95
96 The only required argument is one ``file_name``, which specifies
97 a compilation unit that is a main program. Several ``file_names`` can be
98 specified: this will result in several executables being built.
99 If ``switches`` are present, they can be placed before the first
100 ``file_name``, between ``file_names`` or after the last ``file_name``.
101 If ``mode_switches`` are present, they must always be placed after
102 the last ``file_name`` and all ``switches``.
103
104 If you are using standard file extensions (:file:`.adb` and
105 :file:`.ads`), then the
106 extension may be omitted from the ``file_name`` arguments. However, if
107 you are using non-standard extensions, then it is required that the
108 extension be given. A relative or absolute directory path can be
109 specified in a ``file_name``, in which case, the input source file will
110 be searched for in the specified directory only. Otherwise, the input
111 source file will first be searched in the directory where
112 ``gnatmake`` was invoked and if it is not found, it will be search on
113 the source path of the compiler as described in
114 :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
115
116 All ``gnatmake`` output (except when you specify :switch:`-M`) is sent to
117 :file:`stderr`. The output produced by the
118 :switch:`-M` switch is sent to :file:`stdout`.
119
120
121 .. _Switches_for_gnatmake:
122
123 Switches for ``gnatmake``
124 -------------------------
125
126 You may specify any of the following switches to ``gnatmake``:
127
128
129 .. index:: --version (gnatmake)
130
131 :switch:`--version`
132 Display Copyright and version, then exit disregarding all other options.
133
134
135 .. index:: --help (gnatmake)
136
137 :switch:`--help`
138 If ``--version`` was not used, display usage, then exit disregarding
139 all other options.
140
141
142 .. index:: -P (gnatmake)
143
144 :switch:`-P{project}`
145 Build GNAT project file ``project`` using GPRbuild. When this switch is
146 present, all other command-line switches are treated as GPRbuild switches
147 and not ``gnatmake`` switches.
148
149 .. -- Comment:
150 :ref:`gnatmake_and_Project_Files`.
151
152
153 .. index:: --GCC=compiler_name (gnatmake)
154
155 :switch:`--GCC={compiler_name}`
156 Program used for compiling. The default is ``gcc``. You need to use
157 quotes around ``compiler_name`` if ``compiler_name`` contains
158 spaces or other separator characters.
159 As an example ``--GCC="foo -x -y"``
160 will instruct ``gnatmake`` to use ``foo -x -y`` as your
161 compiler. A limitation of this syntax is that the name and path name of
162 the executable itself must not include any embedded spaces. Note that
163 switch :switch:`-c` is always inserted after your command name. Thus in the
164 above example the compiler command that will be used by ``gnatmake``
165 will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are
166 used, only the last ``compiler_name`` is taken into account. However,
167 all the additional switches are also taken into account. Thus,
168 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
169 ``--GCC="bar -x -y -z -t"``.
170
171
172 .. index:: --GNATBIND=binder_name (gnatmake)
173
174 :switch:`--GNATBIND={binder_name}`
175 Program used for binding. The default is ``gnatbind``. You need to
176 use quotes around ``binder_name`` if ``binder_name`` contains spaces
177 or other separator characters.
178 As an example ``--GNATBIND="bar -x -y"``
179 will instruct ``gnatmake`` to use ``bar -x -y`` as your
180 binder. Binder switches that are normally appended by ``gnatmake``
181 to ``gnatbind`` are now appended to the end of ``bar -x -y``.
182 A limitation of this syntax is that the name and path name of the executable
183 itself must not include any embedded spaces.
184
185 .. index:: --GNATLINK=linker_name (gnatmake)
186
187 :switch:`--GNATLINK={linker_name}`
188 Program used for linking. The default is ``gnatlink``. You need to
189 use quotes around ``linker_name`` if ``linker_name`` contains spaces
190 or other separator characters.
191 As an example ``--GNATLINK="lan -x -y"``
192 will instruct ``gnatmake`` to use ``lan -x -y`` as your
193 linker. Linker switches that are normally appended by ``gnatmake`` to
194 ``gnatlink`` are now appended to the end of ``lan -x -y``.
195 A limitation of this syntax is that the name and path name of the executable
196 itself must not include any embedded spaces.
197
198 :switch:`--create-map-file`
199 When linking an executable, create a map file. The name of the map file
200 has the same name as the executable with extension ".map".
201
202 :switch:`--create-map-file={mapfile}`
203 When linking an executable, create a map file with the specified name.
204
205 .. index:: --create-missing-dirs (gnatmake)
206
207 :switch:`--create-missing-dirs`
208 When using project files (:switch:`-P{project}`), automatically create
209 missing object directories, library directories and exec
210 directories.
211
212 :switch:`--single-compile-per-obj-dir`
213 Disallow simultaneous compilations in the same object directory when
214 project files are used.
215
216 :switch:`--subdirs={subdir}`
217 Actual object directory of each project file is the subdirectory subdir of the
218 object directory specified or defaulted in the project file.
219
220 :switch:`--unchecked-shared-lib-imports`
221 By default, shared library projects are not allowed to import static library
222 projects. When this switch is used on the command line, this restriction is
223 relaxed.
224
225 :switch:`--source-info={source info file}`
226 Specify a source info file. This switch is active only when project files
227 are used. If the source info file is specified as a relative path, then it is
228 relative to the object directory of the main project. If the source info file
229 does not exist, then after the Project Manager has successfully parsed and
230 processed the project files and found the sources, it creates the source info
231 file. If the source info file already exists and can be read successfully,
232 then the Project Manager will get all the needed information about the sources
233 from the source info file and will not look for them. This reduces the time
234 to process the project files, especially when looking for sources that take a
235 long time. If the source info file exists but cannot be parsed successfully,
236 the Project Manager will attempt to recreate it. If the Project Manager fails
237 to create the source info file, a message is issued, but gnatmake does not
238 fail. ``gnatmake`` "trusts" the source info file. This means that
239 if the source files have changed (addition, deletion, moving to a different
240 source directory), then the source info file need to be deleted and recreated.
241
242
243 .. index:: -a (gnatmake)
244
245 :switch:`-a`
246 Consider all files in the make process, even the GNAT internal system
247 files (for example, the predefined Ada library files), as well as any
248 locked files. Locked files are files whose ALI file is write-protected.
249 By default,
250 ``gnatmake`` does not check these files,
251 because the assumption is that the GNAT internal files are properly up
252 to date, and also that any write protected ALI files have been properly
253 installed. Note that if there is an installation problem, such that one
254 of these files is not up to date, it will be properly caught by the
255 binder.
256 You may have to specify this switch if you are working on GNAT
257 itself. The switch ``-a`` is also useful
258 in conjunction with ``-f``
259 if you need to recompile an entire application,
260 including run-time files, using special configuration pragmas,
261 such as a ``Normalize_Scalars`` pragma.
262
263 By default
264 ``gnatmake -a`` compiles all GNAT
265 internal files with
266 ``gcc -c -gnatpg`` rather than ``gcc -c``.
267
268
269 .. index:: -b (gnatmake)
270
271 :switch:`-b`
272 Bind only. Can be combined with :switch:`-c` to do
273 compilation and binding, but no link.
274 Can be combined with :switch:`-l`
275 to do binding and linking. When not combined with
276 :switch:`-c`
277 all the units in the closure of the main program must have been previously
278 compiled and must be up to date. The root unit specified by ``file_name``
279 may be given without extension, with the source extension or, if no GNAT
280 Project File is specified, with the ALI file extension.
281
282
283 .. index:: -c (gnatmake)
284
285 :switch:`-c`
286 Compile only. Do not perform binding, except when :switch:`-b`
287 is also specified. Do not perform linking, except if both
288 :switch:`-b` and
289 :switch:`-l` are also specified.
290 If the root unit specified by ``file_name`` is not a main unit, this is the
291 default. Otherwise ``gnatmake`` will attempt binding and linking
292 unless all objects are up to date and the executable is more recent than
293 the objects.
294
295
296 .. index:: -C (gnatmake)
297
298 :switch:`-C`
299 Use a temporary mapping file. A mapping file is a way to communicate
300 to the compiler two mappings: from unit names to file names (without
301 any directory information) and from file names to path names (with
302 full directory information). A mapping file can make the compiler's
303 file searches faster, especially if there are many source directories,
304 or the sources are read over a slow network connection. If
305 :switch:`-P` is used, a mapping file is always used, so
306 :switch:`-C` is unnecessary; in this case the mapping file
307 is initially populated based on the project file. If
308 :switch:`-C` is used without
309 :switch:`-P`,
310 the mapping file is initially empty. Each invocation of the compiler
311 will add any newly accessed sources to the mapping file.
312
313
314 .. index:: -C= (gnatmake)
315
316 :switch:`-C={file}`
317 Use a specific mapping file. The file, specified as a path name (absolute or
318 relative) by this switch, should already exist, otherwise the switch is
319 ineffective. The specified mapping file will be communicated to the compiler.
320 This switch is not compatible with a project file
321 (-P`file`) or with multiple compiling processes
322 (-jnnn, when nnn is greater than 1).
323
324
325 .. index:: -d (gnatmake)
326
327 :switch:`-d`
328 Display progress for each source, up to date or not, as a single line:
329
330 ::
331
332 completed x out of y (zz%)
333
334 If the file needs to be compiled this is displayed after the invocation of
335 the compiler. These lines are displayed even in quiet output mode.
336
337
338 .. index:: -D (gnatmake)
339
340 :switch:`-D {dir}`
341 Put all object files and ALI file in directory ``dir``.
342 If the :switch:`-D` switch is not used, all object files
343 and ALI files go in the current working directory.
344
345 This switch cannot be used when using a project file.
346
347
348 .. index:: -eI (gnatmake)
349
350 :switch:`-eI{nnn}`
351 Indicates that the main source is a multi-unit source and the rank of the unit
352 in the source file is nnn. nnn needs to be a positive number and a valid
353 index in the source. This switch cannot be used when ``gnatmake`` is
354 invoked for several mains.
355
356
357 .. index:: -eL (gnatmake)
358 .. index:: symbolic links
359
360 :switch:`-eL`
361 Follow all symbolic links when processing project files.
362 This should be used if your project uses symbolic links for files or
363 directories, but is not needed in other cases.
364
365 .. index:: naming scheme
366
367 This also assumes that no directory matches the naming scheme for files (for
368 instance that you do not have a directory called "sources.ads" when using the
369 default GNAT naming scheme).
370
371 When you do not have to use this switch (i.e., by default), gnatmake is able to
372 save a lot of system calls (several per source file and object file), which
373 can result in a significant speed up to load and manipulate a project file,
374 especially when using source files from a remote system.
375
376
377 .. index:: -eS (gnatmake)
378
379 :switch:`-eS`
380 Output the commands for the compiler, the binder and the linker
381 on standard output,
382 instead of standard error.
383
384
385 .. index:: -f (gnatmake)
386
387 :switch:`-f`
388 Force recompilations. Recompile all sources, even though some object
389 files may be up to date, but don't recompile predefined or GNAT internal
390 files or locked files (files with a write-protected ALI file),
391 unless the :switch:`-a` switch is also specified.
392
393
394 .. index:: -F (gnatmake)
395
396 :switch:`-F`
397 When using project files, if some errors or warnings are detected during
398 parsing and verbose mode is not in effect (no use of switch
399 -v), then error lines start with the full path name of the project
400 file, rather than its simple file name.
401
402
403 .. index:: -g (gnatmake)
404
405 :switch:`-g`
406 Enable debugging. This switch is simply passed to the compiler and to the
407 linker.
408
409
410 .. index:: -i (gnatmake)
411
412 :switch:`-i`
413 In normal mode, ``gnatmake`` compiles all object files and ALI files
414 into the current directory. If the :switch:`-i` switch is used,
415 then instead object files and ALI files that already exist are overwritten
416 in place. This means that once a large project is organized into separate
417 directories in the desired manner, then ``gnatmake`` will automatically
418 maintain and update this organization. If no ALI files are found on the
419 Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`),
420 the new object and ALI files are created in the
421 directory containing the source being compiled. If another organization
422 is desired, where objects and sources are kept in different directories,
423 a useful technique is to create dummy ALI files in the desired directories.
424 When detecting such a dummy file, ``gnatmake`` will be forced to
425 recompile the corresponding source file, and it will be put the resulting
426 object and ALI files in the directory where it found the dummy file.
427
428
429 .. index:: -j (gnatmake)
430 .. index:: Parallel make
431
432 :switch:`-j{n}`
433 Use ``n`` processes to carry out the (re)compilations. On a multiprocessor
434 machine compilations will occur in parallel. If ``n`` is 0, then the
435 maximum number of parallel compilations is the number of core processors
436 on the platform. In the event of compilation errors, messages from various
437 compilations might get interspersed (but ``gnatmake`` will give you the
438 full ordered list of failing compiles at the end). If this is problematic,
439 rerun the make process with n set to 1 to get a clean list of messages.
440
441
442 .. index:: -k (gnatmake)
443
444 :switch:`-k`
445 Keep going. Continue as much as possible after a compilation error. To
446 ease the programmer's task in case of compilation errors, the list of
447 sources for which the compile fails is given when ``gnatmake``
448 terminates.
449
450 If ``gnatmake`` is invoked with several :file:`file_names` and with this
451 switch, if there are compilation errors when building an executable,
452 ``gnatmake`` will not attempt to build the following executables.
453
454
455 .. index:: -l (gnatmake)
456
457 :switch:`-l`
458 Link only. Can be combined with :switch:`-b` to binding
459 and linking. Linking will not be performed if combined with
460 :switch:`-c`
461 but not with :switch:`-b`.
462 When not combined with :switch:`-b`
463 all the units in the closure of the main program must have been previously
464 compiled and must be up to date, and the main program needs to have been bound.
465 The root unit specified by ``file_name``
466 may be given without extension, with the source extension or, if no GNAT
467 Project File is specified, with the ALI file extension.
468
469
470 .. index:: -m (gnatmake)
471
472 :switch:`-m`
473 Specify that the minimum necessary amount of recompilations
474 be performed. In this mode ``gnatmake`` ignores time
475 stamp differences when the only
476 modifications to a source file consist in adding/removing comments,
477 empty lines, spaces or tabs. This means that if you have changed the
478 comments in a source file or have simply reformatted it, using this
479 switch will tell ``gnatmake`` not to recompile files that depend on it
480 (provided other sources on which these files depend have undergone no
481 semantic modifications). Note that the debugging information may be
482 out of date with respect to the sources if the :switch:`-m` switch causes
483 a compilation to be switched, so the use of this switch represents a
484 trade-off between compilation time and accurate debugging information.
485
486
487 .. index:: Dependencies, producing list
488 .. index:: -M (gnatmake)
489
490 :switch:`-M`
491 Check if all objects are up to date. If they are, output the object
492 dependences to :file:`stdout` in a form that can be directly exploited in
493 a :file:`Makefile`. By default, each source file is prefixed with its
494 (relative or absolute) directory name. This name is whatever you
495 specified in the various :switch:`-aI`
496 and :switch:`-I` switches. If you use
497 ``gnatmake -M`` :switch:`-q`
498 (see below), only the source file names,
499 without relative paths, are output. If you just specify the :switch:`-M`
500 switch, dependencies of the GNAT internal system files are omitted. This
501 is typically what you want. If you also specify
502 the :switch:`-a` switch,
503 dependencies of the GNAT internal files are also listed. Note that
504 dependencies of the objects in external Ada libraries (see
505 switch :switch:`-aL{dir}` in the following list)
506 are never reported.
507
508
509 .. index:: -n (gnatmake)
510
511 :switch:`-n`
512 Don't compile, bind, or link. Checks if all objects are up to date.
513 If they are not, the full name of the first file that needs to be
514 recompiled is printed.
515 Repeated use of this option, followed by compiling the indicated source
516 file, will eventually result in recompiling all required units.
517
518
519 .. index:: -o (gnatmake)
520
521 :switch:`-o {exec_name}`
522 Output executable name. The name of the final executable program will be
523 ``exec_name``. If the :switch:`-o` switch is omitted the default
524 name for the executable will be the name of the input file in appropriate form
525 for an executable file on the host system.
526
527 This switch cannot be used when invoking ``gnatmake`` with several
528 :file:`file_names`.
529
530
531 .. index:: -p (gnatmake)
532
533 :switch:`-p`
534 Same as :switch:`--create-missing-dirs`
535
536 .. index:: -q (gnatmake)
537
538 :switch:`-q`
539 Quiet. When this flag is not set, the commands carried out by
540 ``gnatmake`` are displayed.
541
542
543 .. index:: -s (gnatmake)
544
545 :switch:`-s`
546 Recompile if compiler switches have changed since last compilation.
547 All compiler switches but -I and -o are taken into account in the
548 following way:
549 orders between different 'first letter' switches are ignored, but
550 orders between same switches are taken into account. For example,
551 :switch:`-O -O2` is different than :switch:`-O2 -O`, but :switch:`-g -O`
552 is equivalent to :switch:`-O -g`.
553
554 This switch is recommended when Integrated Preprocessing is used.
555
556
557 .. index:: -u (gnatmake)
558
559 :switch:`-u`
560 Unique. Recompile at most the main files. It implies -c. Combined with
561 -f, it is equivalent to calling the compiler directly. Note that using
562 -u with a project file and no main has a special meaning.
563
564 .. --Comment
565 (See :ref:`Project_Files_and_Main_Subprograms`.)
566
567
568 .. index:: -U (gnatmake)
569
570 :switch:`-U`
571 When used without a project file or with one or several mains on the command
572 line, is equivalent to -u. When used with a project file and no main
573 on the command line, all sources of all project files are checked and compiled
574 if not up to date, and libraries are rebuilt, if necessary.
575
576
577 .. index:: -v (gnatmake)
578
579 :switch:`-v`
580 Verbose. Display the reason for all recompilations ``gnatmake``
581 decides are necessary, with the highest verbosity level.
582
583
584 .. index:: -vl (gnatmake)
585
586 :switch:`-vl`
587 Verbosity level Low. Display fewer lines than in verbosity Medium.
588
589
590 .. index:: -vm (gnatmake)
591
592 :switch:`-vm`
593 Verbosity level Medium. Potentially display fewer lines than in verbosity High.
594
595
596 .. index:: -vm (gnatmake)
597
598 :switch:`-vh`
599 Verbosity level High. Equivalent to -v.
600
601
602 :switch:`-vP{x}`
603 Indicate the verbosity of the parsing of GNAT project files.
604 See :ref:`Switches_Related_to_Project_Files`.
605
606
607 .. index:: -x (gnatmake)
608
609 :switch:`-x`
610 Indicate that sources that are not part of any Project File may be compiled.
611 Normally, when using Project Files, only sources that are part of a Project
612 File may be compile. When this switch is used, a source outside of all Project
613 Files may be compiled. The ALI file and the object file will be put in the
614 object directory of the main Project. The compilation switches used will only
615 be those specified on the command line. Even when
616 :switch:`-x` is used, mains specified on the
617 command line need to be sources of a project file.
618
619
620 :switch:`-X{name}={value}`
621 Indicate that external variable ``name`` has the value ``value``.
622 The Project Manager will use this value for occurrences of
623 ``external(name)`` when parsing the project file.
624 :ref:`Switches_Related_to_Project_Files`.
625
626
627 .. index:: -z (gnatmake)
628
629 :switch:`-z`
630 No main subprogram. Bind and link the program even if the unit name
631 given on the command line is a package name. The resulting executable
632 will execute the elaboration routines of the package and its closure,
633 then the finalization routines.
634
635
636 .. rubric:: GCC switches
637
638 Any uppercase or multi-character switch that is not a ``gnatmake`` switch
639 is passed to ``gcc`` (e.g., :switch:`-O`, :switch:`-gnato,` etc.)
640
641
642 .. rubric:: Source and library search path switches
643
644 .. index:: -aI (gnatmake)
645
646 :switch:`-aI{dir}`
647 When looking for source files also look in directory ``dir``.
648 The order in which source files search is undertaken is
649 described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`.
650
651
652 .. index:: -aL (gnatmake)
653
654 :switch:`-aL{dir}`
655 Consider ``dir`` as being an externally provided Ada library.
656 Instructs ``gnatmake`` to skip compilation units whose :file:`.ALI`
657 files have been located in directory ``dir``. This allows you to have
658 missing bodies for the units in ``dir`` and to ignore out of date bodies
659 for the same units. You still need to specify
660 the location of the specs for these units by using the switches
661 :switch:`-aI{dir}` or :switch:`-I{dir}`.
662 Note: this switch is provided for compatibility with previous versions
663 of ``gnatmake``. The easier method of causing standard libraries
664 to be excluded from consideration is to write-protect the corresponding
665 ALI files.
666
667
668 .. index:: -aO (gnatmake)
669
670 :switch:`-aO{dir}`
671 When searching for library and object files, look in directory
672 ``dir``. The order in which library files are searched is described in
673 :ref:`Search_Paths_for_gnatbind`.
674
675
676 .. index:: Search paths, for gnatmake
677 .. index:: -A (gnatmake)
678
679 :switch:`-A{dir}`
680 Equivalent to :switch:`-aL{dir}` :switch:`-aI{dir}`.
681
682
683 .. index:: -I (gnatmake)
684
685 :switch:`-I{dir}`
686 Equivalent to :switch:`-aO{dir} -aI{dir}`.
687
688
689 .. index:: -I- (gnatmake)
690 .. index:: Source files, suppressing search
691
692 :switch:`-I-`
693 Do not look for source files in the directory containing the source
694 file named in the command line.
695 Do not look for ALI or object files in the directory
696 where ``gnatmake`` was invoked.
697
698
699 .. index:: -L (gnatmake)
700 .. index:: Linker libraries
701
702 :switch:`-L{dir}`
703 Add directory ``dir`` to the list of directories in which the linker
704 will search for libraries. This is equivalent to
705 :switch:`-largs` :switch:`-L{dir}`.
706 Furthermore, under Windows, the sources pointed to by the libraries path
707 set in the registry are not searched for.
708
709
710 .. index:: -nostdinc (gnatmake)
711
712 :switch:`-nostdinc`
713 Do not look for source files in the system default directory.
714
715
716 .. index:: -nostdlib (gnatmake)
717
718 :switch:`-nostdlib`
719 Do not look for library files in the system default directory.
720
721
722 .. index:: --RTS (gnatmake)
723
724 :switch:`--RTS={rts-path}`
725 Specifies the default location of the run-time library. GNAT looks for the
726 run-time
727 in the following directories, and stops as soon as a valid run-time is found
728 (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or
729 :file:`ada_object_path` present):
730
731 * *<current directory>/$rts_path*
732
733 * *<default-search-dir>/$rts_path*
734
735 * *<default-search-dir>/rts-$rts_path*
736
737 * The selected path is handled like a normal RTS path.
738
739
740 .. _Mode_Switches_for_gnatmake:
741
742 Mode Switches for ``gnatmake``
743 ------------------------------
744
745 The mode switches (referred to as ``mode_switches``) allow the
746 inclusion of switches that are to be passed to the compiler itself, the
747 binder or the linker. The effect of a mode switch is to cause all
748 subsequent switches up to the end of the switch list, or up to the next
749 mode switch, to be interpreted as switches to be passed on to the
750 designated component of GNAT.
751
752 .. index:: -cargs (gnatmake)
753
754 :switch:`-cargs {switches}`
755 Compiler switches. Here ``switches`` is a list of switches
756 that are valid switches for ``gcc``. They will be passed on to
757 all compile steps performed by ``gnatmake``.
758
759
760 .. index:: -bargs (gnatmake)
761
762 :switch:`-bargs {switches}`
763 Binder switches. Here ``switches`` is a list of switches
764 that are valid switches for ``gnatbind``. They will be passed on to
765 all bind steps performed by ``gnatmake``.
766
767
768 .. index:: -largs (gnatmake)
769
770 :switch:`-largs {switches}`
771 Linker switches. Here ``switches`` is a list of switches
772 that are valid switches for ``gnatlink``. They will be passed on to
773 all link steps performed by ``gnatmake``.
774
775
776 .. index:: -margs (gnatmake)
777
778 :switch:`-margs {switches}`
779 Make switches. The switches are directly interpreted by ``gnatmake``,
780 regardless of any previous occurrence of :switch:`-cargs`, :switch:`-bargs`
781 or :switch:`-largs`.
782
783
784 .. _Notes_on_the_Command_Line:
785
786 Notes on the Command Line
787 -------------------------
788
789 This section contains some additional useful notes on the operation
790 of the ``gnatmake`` command.
791
792 .. index:: Recompilation (by gnatmake)
793
794 * If ``gnatmake`` finds no ALI files, it recompiles the main program
795 and all other units required by the main program.
796 This means that ``gnatmake``
797 can be used for the initial compile, as well as during subsequent steps of
798 the development cycle.
799
800 * If you enter ``gnatmake foo.adb``, where ``foo``
801 is a subunit or body of a generic unit, ``gnatmake`` recompiles
802 :file:`foo.adb` (because it finds no ALI) and stops, issuing a
803 warning.
804
805 * In ``gnatmake`` the switch :switch:`-I`
806 is used to specify both source and
807 library file paths. Use :switch:`-aI`
808 instead if you just want to specify
809 source paths only and :switch:`-aO`
810 if you want to specify library paths
811 only.
812
813 * ``gnatmake`` will ignore any files whose ALI file is write-protected.
814 This may conveniently be used to exclude standard libraries from
815 consideration and in particular it means that the use of the
816 :switch:`-f` switch will not recompile these files
817 unless :switch:`-a` is also specified.
818
819 * ``gnatmake`` has been designed to make the use of Ada libraries
820 particularly convenient. Assume you have an Ada library organized
821 as follows: *obj-dir* contains the objects and ALI files for
822 of your Ada compilation units,
823 whereas *include-dir* contains the
824 specs of these units, but no bodies. Then to compile a unit
825 stored in ``main.adb``, which uses this Ada library you would just type:
826
827 .. code-block:: sh
828
829 $ gnatmake -aI`include-dir` -aL`obj-dir` main
830
831 * Using ``gnatmake`` along with the :switch:`-m (minimal recompilation)`
832 switch provides a mechanism for avoiding unnecessary recompilations. Using
833 this switch,
834 you can update the comments/format of your
835 source files without having to recompile everything. Note, however, that
836 adding or deleting lines in a source files may render its debugging
837 info obsolete. If the file in question is a spec, the impact is rather
838 limited, as that debugging info will only be useful during the
839 elaboration phase of your program. For bodies the impact can be more
840 significant. In all events, your debugger will warn you if a source file
841 is more recent than the corresponding object, and alert you to the fact
842 that the debugging information may be out of date.
843
844
845 .. _How_gnatmake_Works:
846
847 How ``gnatmake`` Works
848 ----------------------
849
850 Generally ``gnatmake`` automatically performs all necessary
851 recompilations and you don't need to worry about how it works. However,
852 it may be useful to have some basic understanding of the ``gnatmake``
853 approach and in particular to understand how it uses the results of
854 previous compilations without incorrectly depending on them.
855
856 First a definition: an object file is considered *up to date* if the
857 corresponding ALI file exists and if all the source files listed in the
858 dependency section of this ALI file have time stamps matching those in
859 the ALI file. This means that neither the source file itself nor any
860 files that it depends on have been modified, and hence there is no need
861 to recompile this file.
862
863 ``gnatmake`` works by first checking if the specified main unit is up
864 to date. If so, no compilations are required for the main unit. If not,
865 ``gnatmake`` compiles the main program to build a new ALI file that
866 reflects the latest sources. Then the ALI file of the main unit is
867 examined to find all the source files on which the main program depends,
868 and ``gnatmake`` recursively applies the above procedure on all these
869 files.
870
871 This process ensures that ``gnatmake`` only trusts the dependencies
872 in an existing ALI file if they are known to be correct. Otherwise it
873 always recompiles to determine a new, guaranteed accurate set of
874 dependencies. As a result the program is compiled 'upside down' from what may
875 be more familiar as the required order of compilation in some other Ada
876 systems. In particular, clients are compiled before the units on which
877 they depend. The ability of GNAT to compile in any order is critical in
878 allowing an order of compilation to be chosen that guarantees that
879 ``gnatmake`` will recompute a correct set of new dependencies if
880 necessary.
881
882 When invoking ``gnatmake`` with several ``file_names``, if a unit is
883 imported by several of the executables, it will be recompiled at most once.
884
885 Note: when using non-standard naming conventions
886 (:ref:`Using_Other_File_Names`), changing through a configuration pragmas
887 file the version of a source and invoking ``gnatmake`` to recompile may
888 have no effect, if the previous version of the source is still accessible
889 by ``gnatmake``. It may be necessary to use the switch
890 -f.
891
892
893 .. _Examples_of_gnatmake_Usage:
894
895 Examples of ``gnatmake`` Usage
896 ------------------------------
897
898 ``gnatmake hello.adb``
899 Compile all files necessary to bind and link the main program
900 :file:`hello.adb` (containing unit ``Hello``) and bind and link the
901 resulting object files to generate an executable file :file:`hello`.
902
903 ``gnatmake main1 main2 main3``
904 Compile all files necessary to bind and link the main programs
905 :file:`main1.adb` (containing unit ``Main1``), :file:`main2.adb`
906 (containing unit ``Main2``) and :file:`main3.adb`
907 (containing unit ``Main3``) and bind and link the resulting object files
908 to generate three executable files :file:`main1`,
909 :file:`main2` and :file:`main3`.
910
911 ``gnatmake -q Main_Unit -cargs -O2 -bargs -l``
912 Compile all files necessary to bind and link the main program unit
913 ``Main_Unit`` (from file :file:`main_unit.adb`). All compilations will
914 be done with optimization level 2 and the order of elaboration will be
915 listed by the binder. ``gnatmake`` will operate in quiet mode, not
916 displaying commands it is executing.
917
918
919 .. _Compiling_with_gcc:
920
921 Compiling with ``gcc``
922 ======================
923
924 This section discusses how to compile Ada programs using the ``gcc``
925 command. It also describes the set of switches
926 that can be used to control the behavior of the compiler.
927
928 .. _Compiling_Programs:
929
930 Compiling Programs
931 ------------------
932
933 The first step in creating an executable program is to compile the units
934 of the program using the ``gcc`` command. You must compile the
935 following files:
936
937 * the body file (:file:`.adb`) for a library level subprogram or generic
938 subprogram
939
940 * the spec file (:file:`.ads`) for a library level package or generic
941 package that has no body
942
943 * the body file (:file:`.adb`) for a library level package
944 or generic package that has a body
945
946 You need *not* compile the following files
947
948 * the spec of a library unit which has a body
949
950 * subunits
951
952 because they are compiled as part of compiling related units. GNAT compiles
953 package specs
954 when the corresponding body is compiled, and subunits when the parent is
955 compiled.
956
957 .. index:: cannot generate code
958
959 If you attempt to compile any of these files, you will get one of the
960 following error messages (where ``fff`` is the name of the file you
961 compiled):
962
963 ::
964
965 cannot generate code for file ``fff`` (package spec)
966 to check package spec, use -gnatc
967
968 cannot generate code for file ``fff`` (missing subunits)
969 to check parent unit, use -gnatc
970
971 cannot generate code for file ``fff`` (subprogram spec)
972 to check subprogram spec, use -gnatc
973
974 cannot generate code for file ``fff`` (subunit)
975 to check subunit, use -gnatc
976
977
978 As indicated by the above error messages, if you want to submit
979 one of these files to the compiler to check for correct semantics
980 without generating code, then use the :switch:`-gnatc` switch.
981
982 The basic command for compiling a file containing an Ada unit is:
983
984 .. code-block:: sh
985
986 $ gcc -c [switches] <file name>
987
988 where ``file name`` is the name of the Ada file (usually
989 having an extension :file:`.ads` for a spec or :file:`.adb` for a body).
990 You specify the
991 :switch:`-c` switch to tell ``gcc`` to compile, but not link, the file.
992 The result of a successful compilation is an object file, which has the
993 same name as the source file but an extension of :file:`.o` and an Ada
994 Library Information (ALI) file, which also has the same name as the
995 source file, but with :file:`.ali` as the extension. GNAT creates these
996 two output files in the current directory, but you may specify a source
997 file in any directory using an absolute or relative path specification
998 containing the directory information.
999
1000 .. index:: gnat1
1001
1002 ``gcc`` is actually a driver program that looks at the extensions of
1003 the file arguments and loads the appropriate compiler. For example, the
1004 GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`.
1005 These programs are in directories known to the driver program (in some
1006 configurations via environment variables you set), but need not be in
1007 your path. The ``gcc`` driver also calls the assembler and any other
1008 utilities needed to complete the generation of the required object
1009 files.
1010
1011 It is possible to supply several file names on the same ``gcc``
1012 command. This causes ``gcc`` to call the appropriate compiler for
1013 each file. For example, the following command lists two separate
1014 files to be compiled:
1015
1016 .. code-block:: sh
1017
1018 $ gcc -c x.adb y.adb
1019
1020
1021 calls ``gnat1`` (the Ada compiler) twice to compile :file:`x.adb` and
1022 :file:`y.adb`.
1023 The compiler generates two object files :file:`x.o` and :file:`y.o`
1024 and the two ALI files :file:`x.ali` and :file:`y.ali`.
1025
1026 Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a
1027 list of available ``gcc`` switches.
1028
1029 .. _Search_Paths_and_the_Run-Time_Library_RTL:
1030
1031 Search Paths and the Run-Time Library (RTL)
1032 -------------------------------------------
1033
1034 With the GNAT source-based library system, the compiler must be able to
1035 find source files for units that are needed by the unit being compiled.
1036 Search paths are used to guide this process.
1037
1038 The compiler compiles one source file whose name must be given
1039 explicitly on the command line. In other words, no searching is done
1040 for this file. To find all other source files that are needed (the most
1041 common being the specs of units), the compiler examines the following
1042 directories, in the following order:
1043
1044 * The directory containing the source file of the main unit being compiled
1045 (the file name on the command line).
1046
1047 * Each directory named by an :switch:`-I` switch given on the ``gcc``
1048 command line, in the order given.
1049
1050 .. index:: ADA_PRJ_INCLUDE_FILE
1051
1052 * Each of the directories listed in the text file whose name is given
1053 by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable.
1054 :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat
1055 driver when project files are used. It should not normally be set
1056 by other means.
1057
1058 .. index:: ADA_INCLUDE_PATH
1059
1060 * Each of the directories listed in the value of the
1061 :envvar:`ADA_INCLUDE_PATH` environment variable.
1062 Construct this value
1063 exactly as the :envvar:`PATH` environment variable: a list of directory
1064 names separated by colons (semicolons when working with the NT version).
1065
1066 * The content of the :file:`ada_source_path` file which is part of the GNAT
1067 installation tree and is used to store standard libraries such as the
1068 GNAT Run Time Library (RTL) source files.
1069 See also :ref:`Installing_a_library`.
1070
1071 Specifying the switch :switch:`-I-`
1072 inhibits the use of the directory
1073 containing the source file named in the command line. You can still
1074 have this directory on your search path, but in this case it must be
1075 explicitly requested with a :switch:`-I` switch.
1076
1077 Specifying the switch :switch:`-nostdinc`
1078 inhibits the search of the default location for the GNAT Run Time
1079 Library (RTL) source files.
1080
1081 The compiler outputs its object files and ALI files in the current
1082 working directory.
1083 Caution: The object file can be redirected with the :switch:`-o` switch;
1084 however, ``gcc`` and ``gnat1`` have not been coordinated on this
1085 so the :file:`ALI` file will not go to the right place. Therefore, you should
1086 avoid using the :switch:`-o` switch.
1087
1088 .. index:: System.IO
1089
1090 The packages ``Ada``, ``System``, and ``Interfaces`` and their
1091 children make up the GNAT RTL, together with the simple ``System.IO``
1092 package used in the ``"Hello World"`` example. The sources for these units
1093 are needed by the compiler and are kept together in one directory. Not
1094 all of the bodies are needed, but all of the sources are kept together
1095 anyway. In a normal installation, you need not specify these directory
1096 names when compiling or binding. Either the environment variables or
1097 the built-in defaults cause these files to be found.
1098
1099 In addition to the language-defined hierarchies (``System``, ``Ada`` and
1100 ``Interfaces``), the GNAT distribution provides a fourth hierarchy,
1101 consisting of child units of ``GNAT``. This is a collection of generally
1102 useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual`
1103 for further details.
1104
1105 Besides simplifying access to the RTL, a major use of search paths is
1106 in compiling sources from multiple directories. This can make
1107 development environments much more flexible.
1108
1109 .. _Order_of_Compilation_Issues:
1110
1111 Order of Compilation Issues
1112 ---------------------------
1113
1114 If, in our earlier example, there was a spec for the ``hello``
1115 procedure, it would be contained in the file :file:`hello.ads`; yet this
1116 file would not have to be explicitly compiled. This is the result of the
1117 model we chose to implement library management. Some of the consequences
1118 of this model are as follows:
1119
1120 * There is no point in compiling specs (except for package
1121 specs with no bodies) because these are compiled as needed by clients. If
1122 you attempt a useless compilation, you will receive an error message.
1123 It is also useless to compile subunits because they are compiled as needed
1124 by the parent.
1125
1126 * There are no order of compilation requirements: performing a
1127 compilation never obsoletes anything. The only way you can obsolete
1128 something and require recompilations is to modify one of the
1129 source files on which it depends.
1130
1131 * There is no library as such, apart from the ALI files
1132 (:ref:`The_Ada_Library_Information_Files`, for information on the format
1133 of these files). For now we find it convenient to create separate ALI files,
1134 but eventually the information therein may be incorporated into the object
1135 file directly.
1136
1137 * When you compile a unit, the source files for the specs of all units
1138 that it |withs|, all its subunits, and the bodies of any generics it
1139 instantiates must be available (reachable by the search-paths mechanism
1140 described above), or you will receive a fatal error message.
1141
1142 .. _Examples:
1143
1144 Examples
1145 --------
1146
1147 The following are some typical Ada compilation command line examples:
1148
1149 .. code-block:: sh
1150
1151 $ gcc -c xyz.adb
1152
1153 Compile body in file :file:`xyz.adb` with all default options.
1154
1155 .. code-block:: sh
1156
1157 $ gcc -c -O2 -gnata xyz-def.adb
1158
1159 Compile the child unit package in file :file:`xyz-def.adb` with extensive
1160 optimizations, and pragma ``Assert``/``Debug`` statements
1161 enabled.
1162
1163 .. code-block:: sh
1164
1165 $ gcc -c -gnatc abc-def.adb
1166
1167 Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only
1168 mode.
1169
1170
1171 .. _Switches_for_gcc:
1172
1173 Compiler Switches
1174 =================
1175
1176 The ``gcc`` command accepts switches that control the
1177 compilation process. These switches are fully described in this section:
1178 first an alphabetical listing of all switches with a brief description,
1179 and then functionally grouped sets of switches with more detailed
1180 information.
1181
1182 More switches exist for GCC than those documented here, especially
1183 for specific targets. However, their use is not recommended as
1184 they may change code generation in ways that are incompatible with
1185 the Ada run-time library, or can cause inconsistencies between
1186 compilation units.
1187
1188 .. _Alphabetical_List_of_All_Switches:
1189
1190 Alphabetical List of All Switches
1191 ---------------------------------
1192
1193 .. index:: -b (gcc)
1194
1195 :switch:`-b {target}`
1196 Compile your program to run on ``target``, which is the name of a
1197 system configuration. You must have a GNAT cross-compiler built if
1198 ``target`` is not the same as your host system.
1199
1200
1201 .. index:: -B (gcc)
1202
1203 :switch:`-B{dir}`
1204 Load compiler executables (for example, ``gnat1``, the Ada compiler)
1205 from ``dir`` instead of the default location. Only use this switch
1206 when multiple versions of the GNAT compiler are available.
1207 See the "Options for Directory Search" section in the
1208 :title:`Using the GNU Compiler Collection (GCC)` manual for further details.
1209 You would normally use the :switch:`-b` or :switch:`-V` switch instead.
1210
1211 .. index:: -c (gcc)
1212
1213 :switch:`-c`
1214 Compile. Always use this switch when compiling Ada programs.
1215
1216 Note: for some other languages when using ``gcc``, notably in
1217 the case of C and C++, it is possible to use
1218 use ``gcc`` without a :switch:`-c` switch to
1219 compile and link in one step. In the case of GNAT, you
1220 cannot use this approach, because the binder must be run
1221 and ``gcc`` cannot be used to run the GNAT binder.
1222
1223
1224 .. index:: -fcallgraph-info (gcc)
1225
1226 :switch:`-fcallgraph-info[=su,da]`
1227 Makes the compiler output callgraph information for the program, on a
1228 per-file basis. The information is generated in the VCG format. It can
1229 be decorated with additional, per-node and/or per-edge information, if a
1230 list of comma-separated markers is additionally specified. When the
1231 ``su`` marker is specified, the callgraph is decorated with stack usage
1232 information; it is equivalent to :switch:`-fstack-usage`. When the ``da``
1233 marker is specified, the callgraph is decorated with information about
1234 dynamically allocated objects.
1235
1236 .. index:: -fdiagnostics-format (gcc)
1237
1238 :switch:`-fdiagnostics-format=json`
1239 Makes GNAT emit warning and error messages as JSON. Inhibits printing of
1240 text warning and errors messages except if :switch:`-gnatv` or
1241 :switch:`-gnatl` are present. Uses absolute file paths when used along
1242 :switch:`-gnatef`.
1243
1244
1245 .. index:: -fdump-scos (gcc)
1246
1247 :switch:`-fdump-scos`
1248 Generates SCO (Source Coverage Obligation) information in the ALI file.
1249 This information is used by advanced coverage tools. See unit :file:`SCOs`
1250 in the compiler sources for details in files :file:`scos.ads` and
1251 :file:`scos.adb`.
1252
1253
1254 .. index:: -fgnat-encodings (gcc)
1255
1256 :switch:`-fgnat-encodings=[all|gdb|minimal]`
1257 This switch controls the balance between GNAT encodings and standard DWARF
1258 emitted in the debug information.
1259
1260
1261 .. index:: -flto (gcc)
1262
1263 :switch:`-flto[={n}]`
1264 Enables Link Time Optimization. This switch must be used in conjunction
1265 with the :switch:`-Ox` switches (but not with the :switch:`-gnatn` switch
1266 since it is a full replacement for the latter) and instructs the compiler
1267 to defer most optimizations until the link stage. The advantage of this
1268 approach is that the compiler can do a whole-program analysis and choose
1269 the best interprocedural optimization strategy based on a complete view
1270 of the program, instead of a fragmentary view with the usual approach.
1271 This can also speed up the compilation of big programs and reduce the
1272 size of the executable, compared with a traditional per-unit compilation
1273 with inlining across units enabled by the :switch:`-gnatn` switch.
1274 The drawback of this approach is that it may require more memory and that
1275 the debugging information generated by ``-g`` with it might be hardly usable.
1276 The switch, as well as the accompanying :switch:`-Ox` switches, must be
1277 specified both for the compilation and the link phases.
1278 If the ``n`` parameter is specified, the optimization and final code
1279 generation at link time are executed using ``n`` parallel jobs by
1280 means of an installed ``make`` program.
1281
1282
1283 .. index:: -fno-inline (gcc)
1284
1285 :switch:`-fno-inline`
1286 Suppresses all inlining, unless requested with pragma ``Inline_Always``. The
1287 effect is enforced regardless of other optimization or inlining switches.
1288 Note that inlining can also be suppressed on a finer-grained basis with
1289 pragma ``No_Inline``.
1290
1291
1292 .. index:: -fno-inline-functions (gcc)
1293
1294 :switch:`-fno-inline-functions`
1295 Suppresses automatic inlining of subprograms, which is enabled
1296 if :switch:`-O3` is used.
1297
1298
1299 .. index:: -fno-inline-small-functions (gcc)
1300
1301 :switch:`-fno-inline-small-functions`
1302 Suppresses automatic inlining of small subprograms, which is enabled
1303 if :switch:`-O2` is used.
1304
1305
1306 .. index:: -fno-inline-functions-called-once (gcc)
1307
1308 :switch:`-fno-inline-functions-called-once`
1309 Suppresses inlining of subprograms local to the unit and called once
1310 from within it, which is enabled if :switch:`-O1` is used.
1311
1312
1313 .. index:: -fno-ivopts (gcc)
1314
1315 :switch:`-fno-ivopts`
1316 Suppresses high-level loop induction variable optimizations, which are
1317 enabled if :switch:`-O1` is used. These optimizations are generally
1318 profitable but, for some specific cases of loops with numerous uses
1319 of the iteration variable that follow a common pattern, they may end
1320 up destroying the regularity that could be exploited at a lower level
1321 and thus producing inferior code.
1322
1323
1324 .. index:: -fno-strict-aliasing (gcc)
1325
1326 :switch:`-fno-strict-aliasing`
1327 Causes the compiler to avoid assumptions regarding non-aliasing
1328 of objects of different types. See
1329 :ref:`Optimization_and_Strict_Aliasing` for details.
1330
1331
1332 .. index:: -fno-strict-overflow (gcc)
1333
1334 :switch:`-fno-strict-overflow`
1335 Causes the compiler to avoid assumptions regarding the rules of signed
1336 integer overflow. These rules specify that signed integer overflow will
1337 result in a Constraint_Error exception at run time and are enforced in
1338 default mode by the compiler, so this switch should not be necessary in
1339 normal operating mode. It might be useful in conjunction with :switch:`-gnato0`
1340 for very peculiar cases of low-level programming.
1341
1342
1343 .. index:: -fstack-check (gcc)
1344
1345 :switch:`-fstack-check`
1346 Activates stack checking.
1347 See :ref:`Stack_Overflow_Checking` for details.
1348
1349
1350 .. index:: -fstack-usage (gcc)
1351
1352 :switch:`-fstack-usage`
1353 Makes the compiler output stack usage information for the program, on a
1354 per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details.
1355
1356
1357 .. index:: -g (gcc)
1358
1359 :switch:`-g`
1360 Generate debugging information. This information is stored in the object
1361 file and copied from there to the final executable file by the linker,
1362 where it can be read by the debugger. You must use the
1363 :switch:`-g` switch if you plan on using the debugger.
1364
1365
1366 .. index:: -gnat05 (gcc)
1367
1368 :switch:`-gnat05`
1369 Allow full Ada 2005 features.
1370
1371
1372 .. index:: -gnat12 (gcc)
1373
1374 :switch:`-gnat12`
1375 Allow full Ada 2012 features.
1376
1377 .. index:: -gnat83 (gcc)
1378
1379 .. index:: -gnat2005 (gcc)
1380
1381 :switch:`-gnat2005`
1382 Allow full Ada 2005 features (same as :switch:`-gnat05`)
1383
1384
1385 .. index:: -gnat2012 (gcc)
1386
1387 :switch:`-gnat2012`
1388 Allow full Ada 2012 features (same as :switch:`-gnat12`)
1389
1390
1391 .. index:: -gnat2022 (gcc)
1392
1393 :switch:`-gnat2022`
1394 Allow full Ada 2022 features
1395
1396
1397 :switch:`-gnat83`
1398 Enforce Ada 83 restrictions.
1399
1400
1401 .. index:: -gnat95 (gcc)
1402
1403 :switch:`-gnat95`
1404 Enforce Ada 95 restrictions.
1405
1406 Note: for compatibility with some Ada 95 compilers which support only
1407 the ``overriding`` keyword of Ada 2005, the :switch:`-gnatd.D` switch can
1408 be used along with :switch:`-gnat95` to achieve a similar effect with GNAT.
1409
1410 :switch:`-gnatd.D` instructs GNAT to consider ``overriding`` as a keyword
1411 and handle its associated semantic checks, even in Ada 95 mode.
1412
1413
1414 .. index:: -gnata (gcc)
1415
1416 :switch:`-gnata`
1417 Assertions enabled. ``Pragma Assert`` and ``pragma Debug`` to be
1418 activated. Note that these pragmas can also be controlled using the
1419 configuration pragmas ``Assertion_Policy`` and ``Debug_Policy``.
1420 It also activates pragmas ``Check``, ``Precondition``, and
1421 ``Postcondition``. Note that these pragmas can also be controlled
1422 using the configuration pragma ``Check_Policy``. In Ada 2012, it
1423 also activates all assertions defined in the RM as aspects: preconditions,
1424 postconditions, type invariants and (sub)type predicates. In all Ada modes,
1425 corresponding pragmas for type invariants and (sub)type predicates are
1426 also activated. The default is that all these assertions are disabled,
1427 and have no effect, other than being checked for syntactic validity, and
1428 in the case of subtype predicates, constructions such as membership tests
1429 still test predicates even if assertions are turned off.
1430
1431
1432 .. index:: -gnatA (gcc)
1433
1434 :switch:`-gnatA`
1435 Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present,
1436 it will be ignored.
1437
1438
1439 .. index:: -gnatb (gcc)
1440
1441 :switch:`-gnatb`
1442 Generate brief messages to :file:`stderr` even if verbose mode set.
1443
1444
1445 .. index:: -gnatB (gcc)
1446
1447 :switch:`-gnatB`
1448 Assume no invalid (bad) values except for 'Valid attribute use
1449 (:ref:`Validity_Checking`).
1450
1451
1452 .. index:: -gnatc (gcc)
1453
1454 :switch:`-gnatc`
1455 Check syntax and semantics only (no code generation attempted). When the
1456 compiler is invoked by ``gnatmake``, if the switch :switch:`-gnatc` is
1457 only given to the compiler (after :switch:`-cargs` or in package Compiler of
1458 the project file), ``gnatmake`` will fail because it will not find the
1459 object file after compilation. If ``gnatmake`` is called with
1460 :switch:`-gnatc` as a builder switch (before :switch:`-cargs` or in package
1461 Builder of the project file) then ``gnatmake`` will not fail because
1462 it will not look for the object files after compilation, and it will not try
1463 to build and link.
1464
1465
1466 .. index:: -gnatC (gcc)
1467
1468 :switch:`-gnatC`
1469 Generate CodePeer intermediate format (no code generation attempted).
1470 This switch will generate an intermediate representation suitable for
1471 use by CodePeer (:file:`.scil` files). This switch is not compatible with
1472 code generation (it will, among other things, disable some switches such
1473 as ``-gnatn``, and enable others such as ``-gnata``).
1474
1475
1476 .. index:: -gnatd (gcc)
1477
1478 :switch:`-gnatd`
1479 Specify debug options for the compiler. The string of characters after
1480 the :switch:`-gnatd` specifies the specific debug options. The possible
1481 characters are 0-9, a-z, A-Z, optionally preceded by a dot or underscore.
1482 See compiler source file :file:`debug.adb` for details of the implemented
1483 debug options. Certain debug options are relevant to application
1484 programmers, and these are documented at appropriate points in this
1485 user's guide.
1486
1487
1488 .. index:: -gnatD[nn] (gcc)
1489
1490 :switch:`-gnatD`
1491 Create expanded source files for source level debugging. This switch
1492 also suppresses generation of cross-reference information
1493 (see :switch:`-gnatx`). Note that this switch is not allowed if a previous
1494 ``-gnatR`` switch has been given, since these two switches are not compatible.
1495
1496
1497 .. index:: -gnateA (gcc)
1498
1499 :switch:`-gnateA`
1500 Check that the actual parameters of a subprogram call are not aliases of one
1501 another. To qualify as aliasing, their memory locations must be identical or
1502 overlapping, at least one of the corresponding formal parameters must be of
1503 mode OUT or IN OUT, and at least one of the corresponding formal parameters
1504 must have its parameter passing mechanism not specified.
1505
1506
1507 .. code-block:: ada
1508
1509 type Rec_Typ is record
1510 Data : Integer := 0;
1511 end record;
1512
1513 function Self (Val : Rec_Typ) return Rec_Typ is
1514 begin
1515 return Val;
1516 end Self;
1517
1518 procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is
1519 begin
1520 null;
1521 end Detect_Aliasing;
1522
1523 Obj : Rec_Typ;
1524
1525 Detect_Aliasing (Obj, Obj);
1526 Detect_Aliasing (Obj, Self (Obj));
1527
1528
1529 In the example above, the first call to ``Detect_Aliasing`` fails with a
1530 ``Program_Error`` at run time because the actuals for ``Val_1`` and
1531 ``Val_2`` denote the same object. The second call executes without raising
1532 an exception because ``Self(Obj)`` produces an anonymous object which does
1533 not share the memory location of ``Obj``.
1534
1535 .. index:: -gnateb (gcc)
1536
1537 :switch:`-gnateb`
1538 Store configuration files by their basename in ALI files. This switch is
1539 used for instance by gprbuild for distributed builds in order to prevent
1540 issues where machine-specific absolute paths could end up being stored in
1541 ALI files.
1542
1543 .. index:: -gnatec (gcc)
1544
1545 :switch:`-gnatec={path}`
1546 Specify a configuration pragma file
1547 (the equal sign is optional)
1548 (:ref:`The_Configuration_Pragmas_Files`).
1549
1550
1551 .. index:: -gnateC (gcc)
1552
1553 :switch:`-gnateC`
1554 Generate CodePeer messages in a compiler-like format. This switch is only
1555 effective if :switch:`-gnatcC` is also specified and requires an installation
1556 of CodePeer.
1557
1558
1559 .. index:: -gnated (gcc)
1560
1561 :switch:`-gnated`
1562 Disable atomic synchronization
1563
1564
1565 .. index:: -gnateD (gcc)
1566
1567 :switch:`-gnateDsymbol[={value}]`
1568 Defines a symbol, associated with ``value``, for preprocessing.
1569 (:ref:`Integrated_Preprocessing`).
1570
1571
1572 .. index:: -gnateE (gcc)
1573
1574 :switch:`-gnateE`
1575 Generate extra information in exception messages. In particular, display
1576 extra column information and the value and range associated with index and
1577 range check failures, and extra column information for access checks.
1578 In cases where the compiler is able to determine at compile time that
1579 a check will fail, it gives a warning, and the extra information is not
1580 produced at run time.
1581
1582
1583 .. index:: -gnatef (gcc)
1584
1585 :switch:`-gnatef`
1586 Display full source path name in brief error messages and absolute paths in
1587 :switch:`-fdiagnostics-format=json`'s output.
1588
1589
1590 .. index:: -gnateF (gcc)
1591
1592 :switch:`-gnateF`
1593 Check for overflow on all floating-point operations, including those
1594 for unconstrained predefined types. See description of pragma
1595 ``Check_Float_Overflow`` in GNAT RM.
1596
1597
1598 .. index:: -gnateg (gcc)
1599
1600 :switch:`-gnateg`
1601 :switch:`-gnatceg`
1602
1603 The :switch:`-gnatc` switch must always be specified before this switch, e.g.
1604 :switch:`-gnatceg`. Generate a C header from the Ada input file. See
1605 :ref:`Generating_C_Headers_for_Ada_Specifications` for more
1606 information.
1607
1608
1609 .. index:: -gnateG (gcc)
1610
1611 :switch:`-gnateG`
1612 Save result of preprocessing in a text file.
1613
1614
1615 .. index:: -gnateH (gcc)
1616
1617 :switch:`-gnateH`
1618 Set the threshold from which the RM 13.5.1(13.3/2) clause applies to 64.
1619 This is useful only on 64-bit plaforms where this threshold is 128, but
1620 used to be 64 in earlier versions of the compiler.
1621
1622
1623 .. index:: -gnatei (gcc)
1624
1625 :switch:`-gnatei{nnn}`
1626 Set maximum number of instantiations during compilation of a single unit to
1627 ``nnn``. This may be useful in increasing the default maximum of 8000 for
1628 the rare case when a single unit legitimately exceeds this limit.
1629
1630
1631 .. index:: -gnateI (gcc)
1632
1633 :switch:`-gnateI{nnn}`
1634 Indicates that the source is a multi-unit source and that the index of the
1635 unit to compile is ``nnn``. ``nnn`` needs to be a positive number and need
1636 to be a valid index in the multi-unit source.
1637
1638
1639 .. index:: -gnatel (gcc)
1640
1641 :switch:`-gnatel`
1642 This switch can be used with the static elaboration model to issue info
1643 messages showing
1644 where implicit ``pragma Elaborate`` and ``pragma Elaborate_All``
1645 are generated. This is useful in diagnosing elaboration circularities
1646 caused by these implicit pragmas when using the static elaboration
1647 model. See the section in this guide on elaboration checking for
1648 further details. These messages are not generated by default, and are
1649 intended only for temporary use when debugging circularity problems.
1650
1651
1652 .. index:: -gnatel (gcc)
1653
1654 :switch:`-gnateL`
1655 This switch turns off the info messages about implicit elaboration pragmas.
1656
1657
1658 .. index:: -gnatem (gcc)
1659
1660 :switch:`-gnatem={path}`
1661 Specify a mapping file
1662 (the equal sign is optional)
1663 (:ref:`Units_to_Sources_Mapping_Files`).
1664
1665
1666 .. index:: -gnatep (gcc)
1667
1668 :switch:`-gnatep={file}`
1669 Specify a preprocessing data file
1670 (the equal sign is optional)
1671 (:ref:`Integrated_Preprocessing`).
1672
1673
1674 .. index:: -gnateP (gcc)
1675
1676 :switch:`-gnateP`
1677 Turn categorization dependency errors into warnings.
1678 Ada requires that units that WITH one another have compatible categories, for
1679 example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
1680 these errors become warnings (which can be ignored, or suppressed in the usual
1681 manner). This can be useful in some specialized circumstances such as the
1682 temporary use of special test software.
1683
1684
1685 .. index:: -gnateS (gcc)
1686
1687 :switch:`-gnateS`
1688 Synonym of :switch:`-fdump-scos`, kept for backwards compatibility.
1689
1690
1691 .. index:: -gnatet=file (gcc)
1692
1693 :switch:`-gnatet={path}`
1694 Generate target dependent information. The format of the output file is
1695 described in the section about switch :switch:`-gnateT`.
1696
1697
1698 .. index:: -gnateT (gcc)
1699
1700 :switch:`-gnateT={path}`
1701 Read target dependent information, such as endianness or sizes and alignments
1702 of base type. If this switch is passed, the default target dependent
1703 information of the compiler is replaced by the one read from the input file.
1704 This is used by tools other than the compiler, e.g. to do
1705 semantic analysis of programs that will run on some other target than
1706 the machine on which the tool is run.
1707
1708 The following target dependent values should be defined,
1709 where ``Nat`` denotes a natural integer value, ``Pos`` denotes a
1710 positive integer value, and fields marked with a question mark are
1711 boolean fields, where a value of 0 is False, and a value of 1 is True:
1712
1713
1714 ::
1715
1716 Bits_BE : Nat; -- Bits stored big-endian?
1717 Bits_Per_Unit : Pos; -- Bits in a storage unit
1718 Bits_Per_Word : Pos; -- Bits in a word
1719 Bytes_BE : Nat; -- Bytes stored big-endian?
1720 Char_Size : Pos; -- Standard.Character'Size
1721 Double_Float_Alignment : Nat; -- Alignment of double float
1722 Double_Scalar_Alignment : Nat; -- Alignment of double length scalar
1723 Double_Size : Pos; -- Standard.Long_Float'Size
1724 Float_Size : Pos; -- Standard.Float'Size
1725 Float_Words_BE : Nat; -- Float words stored big-endian?
1726 Int_Size : Pos; -- Standard.Integer'Size
1727 Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size
1728 Long_Long_Long_Size : Pos; -- Standard.Long_Long_Long_Integer'Size
1729 Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size
1730 Long_Size : Pos; -- Standard.Long_Integer'Size
1731 Maximum_Alignment : Pos; -- Maximum permitted alignment
1732 Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field
1733 Pointer_Size : Pos; -- System.Address'Size
1734 Short_Enums : Nat; -- Foreign enums use short size?
1735 Short_Size : Pos; -- Standard.Short_Integer'Size
1736 Strict_Alignment : Nat; -- Strict alignment?
1737 System_Allocator_Alignment : Nat; -- Alignment for malloc calls
1738 Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size
1739 Words_BE : Nat; -- Words stored big-endian?
1740
1741 ``Bits_Per_Unit`` is the number of bits in a storage unit, the equivalent of
1742 GCC macro ``BITS_PER_UNIT`` documented as follows: `Define this macro to be
1743 the number of bits in an addressable storage unit (byte); normally 8.`
1744
1745 ``Bits_Per_Word`` is the number of bits in a machine word, the equivalent of
1746 GCC macro ``BITS_PER_WORD`` documented as follows: `Number of bits in a word;
1747 normally 32.`
1748
1749 ``Double_Float_Alignment``, if not zero, is the maximum alignment that the
1750 compiler can choose by default for a 64-bit floating-point type or object.
1751
1752 ``Double_Scalar_Alignment``, if not zero, is the maximum alignment that the
1753 compiler can choose by default for a 64-bit or larger scalar type or object.
1754
1755 ``Maximum_Alignment`` is the maximum alignment that the compiler can choose
1756 by default for a type or object, which is also the maximum alignment that can
1757 be specified in GNAT. It is computed for GCC back ends as ``BIGGEST_ALIGNMENT
1758 / BITS_PER_UNIT`` where GCC macro ``BIGGEST_ALIGNMENT`` is documented as
1759 follows: `Biggest alignment that any data type can require on this machine,
1760 in bits.`
1761
1762 ``Max_Unaligned_Field`` is the maximum size for unaligned bit field, which is
1763 64 for the majority of GCC targets (but can be different on some targets).
1764
1765 ``Strict_Alignment`` is the equivalent of GCC macro ``STRICT_ALIGNMENT``
1766 documented as follows: `Define this macro to be the value 1 if instructions
1767 will fail to work if given data not on the nominal alignment. If instructions
1768 will merely go slower in that case, define this macro as 0.`
1769
1770 ``System_Allocator_Alignment`` is the guaranteed alignment of data returned
1771 by calls to ``malloc``.
1772
1773
1774 The format of the input file is as follows. First come the values of
1775 the variables defined above, with one line per value:
1776
1777
1778 ::
1779
1780 name value
1781
1782 where ``name`` is the name of the parameter, spelled out in full,
1783 and cased as in the above list, and ``value`` is an unsigned decimal
1784 integer. Two or more blanks separates the name from the value.
1785
1786 All the variables must be present, in alphabetical order (i.e. the
1787 same order as the list above).
1788
1789 Then there is a blank line to separate the two parts of the file. Then
1790 come the lines showing the floating-point types to be registered, with
1791 one line per registered mode:
1792
1793
1794 ::
1795
1796 name digs float_rep size alignment
1797
1798
1799 where ``name`` is the string name of the type (which can have
1800 single spaces embedded in the name, e.g. long double), ``digs`` is
1801 the number of digits for the floating-point type, ``float_rep`` is
1802 the float representation (I for IEEE-754-Binary, which is
1803 the only one supported at this time),
1804 ``size`` is the size in bits, ``alignment`` is the
1805 alignment in bits. The name is followed by at least two blanks, fields
1806 are separated by at least one blank, and a LF character immediately
1807 follows the alignment field.
1808
1809 Here is an example of a target parameterization file:
1810
1811
1812 ::
1813
1814 Bits_BE 0
1815 Bits_Per_Unit 8
1816 Bits_Per_Word 64
1817 Bytes_BE 0
1818 Char_Size 8
1819 Double_Float_Alignment 0
1820 Double_Scalar_Alignment 0
1821 Double_Size 64
1822 Float_Size 32
1823 Float_Words_BE 0
1824 Int_Size 64
1825 Long_Double_Size 128
1826 Long_Long_Long_Size 128
1827 Long_Long_Size 64
1828 Long_Size 64
1829 Maximum_Alignment 16
1830 Max_Unaligned_Field 64
1831 Pointer_Size 64
1832 Short_Size 16
1833 Strict_Alignment 0
1834 System_Allocator_Alignment 16
1835 Wchar_T_Size 32
1836 Words_BE 0
1837
1838 float 15 I 64 64
1839 double 15 I 64 64
1840 long double 18 I 80 128
1841 TF 33 I 128 128
1842
1843
1844
1845 .. index:: -gnateu (gcc)
1846
1847 :switch:`-gnateu`
1848 Ignore unrecognized validity, warning, and style switches that
1849 appear after this switch is given. This may be useful when
1850 compiling sources developed on a later version of the compiler
1851 with an earlier version. Of course the earlier version must
1852 support this switch.
1853
1854
1855 .. index:: -gnateV (gcc)
1856
1857 :switch:`-gnateV`
1858 Check that all actual parameters of a subprogram call are valid according to
1859 the rules of validity checking (:ref:`Validity_Checking`).
1860
1861
1862 .. index:: -gnateY (gcc)
1863
1864 :switch:`-gnateY`
1865 Ignore all STYLE_CHECKS pragmas. Full legality checks
1866 are still carried out, but the pragmas have no effect
1867 on what style checks are active. This allows all style
1868 checking options to be controlled from the command line.
1869
1870
1871 .. index:: -gnatE (gcc)
1872
1873 :switch:`-gnatE`
1874 Dynamic elaboration checking mode enabled. For further details see
1875 :ref:`Elaboration_Order_Handling_in_GNAT`.
1876
1877
1878 .. index:: -gnatf (gcc)
1879
1880 :switch:`-gnatf`
1881 Full errors. Multiple errors per line, all undefined references, do not
1882 attempt to suppress cascaded errors.
1883
1884
1885 .. index:: -gnatF (gcc)
1886
1887 :switch:`-gnatF`
1888 Externals names are folded to all uppercase.
1889
1890
1891 .. index:: -gnatg (gcc)
1892
1893 :switch:`-gnatg`
1894 Internal GNAT implementation mode. This should not be used for applications
1895 programs, it is intended only for use by the compiler and its run-time
1896 library. For documentation, see the GNAT sources. Note that :switch:`-gnatg`
1897 implies :switch:`-gnatw.ge` and :switch:`-gnatyg` so that all standard
1898 warnings and all standard style options are turned on. All warnings and style
1899 messages are treated as errors.
1900
1901
1902 .. index:: -gnatG[nn] (gcc)
1903
1904 :switch:`-gnatG=nn`
1905 List generated expanded code in source form.
1906
1907
1908 .. index:: -gnath (gcc)
1909
1910 :switch:`-gnath`
1911 Output usage information. The output is written to :file:`stdout`.
1912
1913
1914 .. index:: -gnatH (gcc)
1915
1916 :switch:`-gnatH`
1917 Legacy elaboration-checking mode enabled. When this switch is in effect,
1918 the pre-18.x access-before-elaboration model becomes the de facto model.
1919 For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1920
1921
1922 .. index:: -gnati (gcc)
1923
1924 :switch:`-gnati{c}`
1925 Identifier character set (``c`` = 1/2/3/4/5/9/p/8/f/n/w).
1926 For details of the possible selections for ``c``,
1927 see :ref:`Character_Set_Control`.
1928
1929
1930 .. index:: -gnatI (gcc)
1931
1932 :switch:`-gnatI`
1933 Ignore representation clauses. When this switch is used,
1934 representation clauses are treated as comments. This is useful
1935 when initially porting code where you want to ignore rep clause
1936 problems, and also for compiling foreign code (particularly
1937 for use with ASIS). The representation clauses that are ignored
1938 are: enumeration_representation_clause, record_representation_clause,
1939 and attribute_definition_clause for the following attributes:
1940 Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
1941 Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
1942 and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
1943 Note that this option should be used only for compiling -- the
1944 code is likely to malfunction at run time.
1945
1946
1947 .. index:: -gnatjnn (gcc)
1948
1949 :switch:`-gnatj{nn}`
1950 Reformat error messages to fit on ``nn`` character lines
1951
1952
1953 .. index:: -gnatJ (gcc)
1954
1955 :switch:`-gnatJ`
1956 Permissive elaboration-checking mode enabled. When this switch is in effect,
1957 the post-18.x access-before-elaboration model ignores potential issues with:
1958
1959 - Accept statements
1960 - Activations of tasks defined in instances
1961 - Assertion pragmas
1962 - Calls from within an instance to its enclosing context
1963 - Calls through generic formal parameters
1964 - Calls to subprograms defined in instances
1965 - Entry calls
1966 - Indirect calls using 'Access
1967 - Requeue statements
1968 - Select statements
1969 - Synchronous task suspension
1970
1971 and does not emit compile-time diagnostics or run-time checks. For further
1972 details see :ref:`Elaboration_Order_Handling_in_GNAT`.
1973
1974
1975 .. index:: -gnatk (gcc)
1976
1977 :switch:`-gnatk={n}`
1978 Limit file names to ``n`` (1-999) characters (``k`` = krunch).
1979
1980
1981 .. index:: -gnatl (gcc)
1982
1983 :switch:`-gnatl`
1984 Output full source listing with embedded error messages.
1985
1986
1987 .. index:: -gnatL (gcc)
1988
1989 :switch:`-gnatL`
1990 Used in conjunction with -gnatG or -gnatD to intersperse original
1991 source lines (as comment lines with line numbers) in the expanded
1992 source output.
1993
1994
1995 .. index:: -gnatm (gcc)
1996
1997 :switch:`-gnatm={n}`
1998 Limit number of detected error or warning messages to ``n``
1999 where ``n`` is in the range 1..999999. The default setting if
2000 no switch is given is 9999. If the number of warnings reaches this
2001 limit, then a message is output and further warnings are suppressed,
2002 but the compilation is continued. If the number of error messages
2003 reaches this limit, then a message is output and the compilation
2004 is abandoned. The equal sign here is optional. A value of zero
2005 means that no limit applies.
2006
2007
2008 .. index:: -gnatn (gcc)
2009
2010 :switch:`-gnatn[12]`
2011 Activate inlining across units for subprograms for which pragma ``Inline``
2012 is specified. This inlining is performed by the GCC back end. An optional
2013 digit sets the inlining level: 1 for moderate inlining across units
2014 or 2 for full inlining across units. If no inlining level is specified,
2015 the compiler will pick it based on the optimization level.
2016
2017
2018 .. index:: -gnatN (gcc)
2019
2020 :switch:`-gnatN`
2021 Activate front end inlining for subprograms for which
2022 pragma ``Inline`` is specified. This inlining is performed
2023 by the front end and will be visible in the
2024 :switch:`-gnatG` output.
2025
2026 When using a gcc-based back end, then the use of
2027 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
2028 Historically front end inlining was more extensive than the gcc back end
2029 inlining, but that is no longer the case.
2030
2031
2032 .. index:: -gnato0 (gcc)
2033
2034 :switch:`-gnato0`
2035 Suppresses overflow checking. This causes the behavior of the compiler to
2036 match the default for older versions where overflow checking was suppressed
2037 by default. This is equivalent to having
2038 ``pragma Suppress (Overflow_Check)`` in a configuration pragma file.
2039
2040
2041 .. index:: -gnato?? (gcc)
2042
2043 :switch:`-gnato??`
2044 Set default mode for handling generation of code to avoid intermediate
2045 arithmetic overflow. Here ``??`` is two digits, a
2046 single digit, or nothing. Each digit is one of the digits ``1``
2047 through ``3``:
2048
2049 ===== ===============================================================
2050 Digit Interpretation
2051 ----- ---------------------------------------------------------------
2052 *1* All intermediate overflows checked against base type (``STRICT``)
2053 *2* Minimize intermediate overflows (``MINIMIZED``)
2054 *3* Eliminate intermediate overflows (``ELIMINATED``)
2055 ===== ===============================================================
2056
2057 If only one digit appears, then it applies to all
2058 cases; if two digits are given, then the first applies outside
2059 assertions, pre/postconditions, and type invariants, and the second
2060 applies within assertions, pre/postconditions, and type invariants.
2061
2062 If no digits follow the :switch:`-gnato`, then it is equivalent to
2063 :switch:`-gnato11`,
2064 causing all intermediate overflows to be handled in strict
2065 mode.
2066
2067 This switch also causes arithmetic overflow checking to be performed
2068 (as though ``pragma Unsuppress (Overflow_Check)`` had been specified).
2069
2070 The default if no option :switch:`-gnato` is given is that overflow handling
2071 is in ``STRICT`` mode (computations done using the base type), and that
2072 overflow checking is enabled.
2073
2074 Note that division by zero is a separate check that is not
2075 controlled by this switch (divide-by-zero checking is on by default).
2076
2077 See also :ref:`Specifying_the_Desired_Mode`.
2078
2079
2080 .. index:: -gnatp (gcc)
2081
2082 :switch:`-gnatp`
2083 Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch
2084 has no effect if cancelled by a subsequent :switch:`-gnat-p` switch.
2085
2086
2087 .. index:: -gnat-p (gcc)
2088
2089 :switch:`-gnat-p`
2090 Cancel effect of previous :switch:`-gnatp` switch.
2091
2092
2093 .. index:: -gnatq (gcc)
2094
2095 :switch:`-gnatq`
2096 Don't quit. Try semantics, even if parse errors.
2097
2098
2099 .. index:: -gnatQ (gcc)
2100
2101 :switch:`-gnatQ`
2102 Don't quit. Generate :file:`ALI` and tree files even if illegalities.
2103 Note that code generation is still suppressed in the presence of any
2104 errors, so even with :switch:`-gnatQ` no object file is generated.
2105
2106
2107 .. index:: -gnatr (gcc)
2108
2109 :switch:`-gnatr`
2110 Treat pragma Restrictions as Restriction_Warnings.
2111
2112
2113 .. index:: -gnatR (gcc)
2114
2115 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
2116 Output representation information for declared types, objects and
2117 subprograms. Note that this switch is not allowed if a previous
2118 :switch:`-gnatD` switch has been given, since these two switches
2119 are not compatible.
2120
2121
2122 .. index:: -gnats (gcc)
2123
2124 :switch:`-gnats`
2125 Syntax check only.
2126
2127
2128 .. index:: -gnatS (gcc)
2129
2130 :switch:`-gnatS`
2131 Print package Standard.
2132
2133
2134 .. index:: -gnatT (gcc)
2135
2136 :switch:`-gnatT{nnn}`
2137 All compiler tables start at ``nnn`` times usual starting size.
2138
2139
2140 .. index:: -gnatu (gcc)
2141
2142 :switch:`-gnatu`
2143 List units for this compilation.
2144
2145
2146 .. index:: -gnatU (gcc)
2147
2148 :switch:`-gnatU`
2149 Tag all error messages with the unique string 'error:'
2150
2151
2152 .. index:: -gnatv (gcc)
2153
2154 :switch:`-gnatv`
2155 Verbose mode. Full error output with source lines to :file:`stdout`.
2156
2157
2158 .. index:: -gnatV (gcc)
2159
2160 :switch:`-gnatV`
2161 Control level of validity checking (:ref:`Validity_Checking`).
2162
2163
2164 .. index:: -gnatw (gcc)
2165
2166 :switch:`-gnatw{xxx}`
2167 Warning mode where
2168 ``xxx`` is a string of option letters that denotes
2169 the exact warnings that
2170 are enabled or disabled (:ref:`Warning_Message_Control`).
2171
2172
2173 .. index:: -gnatW (gcc)
2174
2175 :switch:`-gnatW{e}`
2176 Wide character encoding method
2177 (``e``\ =n/h/u/s/e/8).
2178
2179
2180 .. index:: -gnatx (gcc)
2181
2182 :switch:`-gnatx`
2183 Suppress generation of cross-reference information.
2184
2185
2186 .. index:: -gnatX (gcc)
2187
2188 :switch:`-gnatX`
2189 Enable core GNAT implementation extensions and latest Ada version.
2190
2191
2192 .. index:: -gnatX0 (gcc)
2193
2194 :switch:`-gnatX0`
2195 Enable all GNAT implementation extensions and latest Ada version.
2196
2197
2198 .. index:: -gnaty (gcc)
2199
2200 :switch:`-gnaty`
2201 Enable built-in style checks (:ref:`Style_Checking`).
2202
2203
2204 .. index:: -gnatz (gcc)
2205
2206 :switch:`-gnatz{m}`
2207 Distribution stub generation and compilation
2208 (``m``\ =r/c for receiver/caller stubs).
2209
2210
2211 .. index:: -I (gcc)
2212
2213 :switch:`-I{dir}`
2214 .. index:: RTL
2215
2216 Direct GNAT to search the ``dir`` directory for source files needed by
2217 the current compilation
2218 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2219
2220
2221 .. index:: -I- (gcc)
2222
2223 :switch:`-I-`
2224 .. index:: RTL
2225
2226 Except for the source file named in the command line, do not look for source
2227 files in the directory containing the source file named in the command line
2228 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
2229
2230
2231 .. index:: -o (gcc)
2232
2233 :switch:`-o {file}`
2234 This switch is used in ``gcc`` to redirect the generated object file
2235 and its associated ALI file. Beware of this switch with GNAT, because it may
2236 cause the object file and ALI file to have different names which in turn
2237 may confuse the binder and the linker.
2238
2239
2240 .. index:: -nostdinc (gcc)
2241
2242 :switch:`-nostdinc`
2243 Inhibit the search of the default location for the GNAT Run Time
2244 Library (RTL) source files.
2245
2246
2247 .. index:: -nostdlib (gcc)
2248
2249 :switch:`-nostdlib`
2250 Inhibit the search of the default location for the GNAT Run Time
2251 Library (RTL) ALI files.
2252
2253
2254 .. index:: -O (gcc)
2255
2256 :switch:`-O[{n}]`
2257 ``n`` controls the optimization level:
2258
2259 ======= ==================================================================
2260 *n* Effect
2261 ------- ------------------------------------------------------------------
2262 *0* No optimization, the default setting if no :switch:`-O` appears.
2263 *1* Moderate optimization, same as :switch:`-O` without an operand.
2264 A good compromise between code quality and compilation time.
2265 *2* Extensive optimization, should improve execution time, possibly at
2266 the cost of substantially increased compilation time.
2267 *3* Full optimization, may further improve execution time, possibly at
2268 the cost of substantially larger generated code.
2269 *s* Optimize for size (code and data) rather than speed.
2270 *z* Optimize aggressively for size (code and data) rather than speed.
2271 *g* Optimize for debugging experience rather than speed.
2272 ======= ==================================================================
2273
2274 See also :ref:`Optimization_Levels`.
2275
2276
2277 .. index:: -pass-exit-codes (gcc)
2278
2279 :switch:`-pass-exit-codes`
2280 Catch exit codes from the compiler and use the most meaningful as
2281 exit status.
2282
2283
2284 .. index:: --RTS (gcc)
2285
2286 :switch:`--RTS={rts-path}`
2287 Specifies the default location of the run-time library. Same meaning as the
2288 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
2289
2290
2291 .. index:: -S (gcc)
2292
2293 :switch:`-S`
2294 Used in place of :switch:`-c` to
2295 cause the assembler source file to be
2296 generated, using :file:`.s` as the extension,
2297 instead of the object file.
2298 This may be useful if you need to examine the generated assembly code.
2299
2300
2301 .. index:: -fverbose-asm (gcc)
2302
2303 :switch:`-fverbose-asm`
2304 Used in conjunction with :switch:`-S`
2305 to cause the generated assembly code file to be annotated with variable
2306 names, making it significantly easier to follow.
2307
2308
2309 .. index:: -v (gcc)
2310
2311 :switch:`-v`
2312 Show commands generated by the ``gcc`` driver. Normally used only for
2313 debugging purposes or if you need to be sure what version of the
2314 compiler you are executing.
2315
2316
2317 .. index:: -V (gcc)
2318
2319 :switch:`-V {ver}`
2320 Execute ``ver`` version of the compiler. This is the ``gcc``
2321 version, not the GNAT version.
2322
2323
2324 .. index:: -w (gcc)
2325
2326 :switch:`-w`
2327 Turn off warnings generated by the back end of the compiler. Use of
2328 this switch also causes the default for front end warnings to be set
2329 to suppress (as though :switch:`-gnatws` had appeared at the start of
2330 the options).
2331
2332
2333 .. index:: Combining GNAT switches
2334
2335 You may combine a sequence of GNAT switches into a single switch. For
2336 example, the combined switch
2337
2338 ::
2339
2340 -gnatofi3
2341
2342 is equivalent to specifying the following sequence of switches:
2343
2344 ::
2345
2346 -gnato -gnatf -gnati3
2347
2348 The following restrictions apply to the combination of switches
2349 in this manner:
2350
2351 * The switch :switch:`-gnatc` if combined with other switches must come
2352 first in the string.
2353
2354 * The switch :switch:`-gnats` if combined with other switches must come
2355 first in the string.
2356
2357 * The switches
2358 :switch:`-gnatzc` and :switch:`-gnatzr` may not be combined with any other
2359 switches, and only one of them may appear in the command line.
2360
2361 * The switch :switch:`-gnat-p` may not be combined with any other switch.
2362
2363 * Once a 'y' appears in the string (that is a use of the :switch:`-gnaty`
2364 switch), then all further characters in the switch are interpreted
2365 as style modifiers (see description of :switch:`-gnaty`).
2366
2367 * Once a 'd' appears in the string (that is a use of the :switch:`-gnatd`
2368 switch), then all further characters in the switch are interpreted
2369 as debug flags (see description of :switch:`-gnatd`).
2370
2371 * Once a 'w' appears in the string (that is a use of the :switch:`-gnatw`
2372 switch), then all further characters in the switch are interpreted
2373 as warning mode modifiers (see description of :switch:`-gnatw`).
2374
2375 * Once a 'V' appears in the string (that is a use of the :switch:`-gnatV`
2376 switch), then all further characters in the switch are interpreted
2377 as validity checking options (:ref:`Validity_Checking`).
2378
2379 * Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
2380 a combined list of options.
2381
2382 .. _Output_and_Error_Message_Control:
2383
2384 Output and Error Message Control
2385 --------------------------------
2386
2387 .. index:: stderr
2388
2389 The standard default format for error messages is called 'brief format'.
2390 Brief format messages are written to :file:`stderr` (the standard error
2391 file) and have the following form:
2392
2393 ::
2394
2395 e.adb:3:04: Incorrect spelling of keyword "function"
2396 e.adb:4:20: ";" should be "is"
2397
2398 The first integer after the file name is the line number in the file,
2399 and the second integer is the column number within the line.
2400 ``GNAT Studio`` can parse the error messages
2401 and point to the referenced character.
2402 The following switches provide control over the error message
2403 format:
2404
2405
2406 .. index:: -gnatv (gcc)
2407
2408 :switch:`-gnatv`
2409 The ``v`` stands for verbose.
2410 The effect of this setting is to write long-format error
2411 messages to :file:`stdout` (the standard output file).
2412 The same program compiled with the
2413 :switch:`-gnatv` switch would generate:
2414
2415 ::
2416
2417 3. funcion X (Q : Integer)
2418 |
2419 >>> Incorrect spelling of keyword "function"
2420 4. return Integer;
2421 |
2422 >>> ";" should be "is"
2423
2424
2425 The vertical bar indicates the location of the error, and the ``>>>``
2426 prefix can be used to search for error messages. When this switch is
2427 used the only source lines output are those with errors.
2428
2429
2430 .. index:: -gnatl (gcc)
2431
2432 :switch:`-gnatl`
2433 The ``l`` stands for list.
2434 This switch causes a full listing of
2435 the file to be generated. In the case where a body is
2436 compiled, the corresponding spec is also listed, along
2437 with any subunits. Typical output from compiling a package
2438 body :file:`p.adb` might look like::
2439
2440 Compiling: p.adb
2441
2442 1. package body p is
2443 2. procedure a;
2444 3. procedure a is separate;
2445 4. begin
2446 5. null
2447 |
2448 >>> missing ";"
2449
2450 6. end;
2451
2452 Compiling: p.ads
2453
2454 1. package p is
2455 2. pragma Elaborate_Body
2456 |
2457 >>> missing ";"
2458
2459 3. end p;
2460
2461 Compiling: p-a.adb
2462
2463 1. separate p
2464 |
2465 >>> missing "("
2466
2467 2. procedure a is
2468 3. begin
2469 4. null
2470 |
2471 >>> missing ";"
2472
2473 5. end;
2474
2475
2476 When you specify the :switch:`-gnatv` or :switch:`-gnatl` switches and
2477 standard output is redirected, a brief summary is written to
2478 :file:`stderr` (standard error) giving the number of error messages and
2479 warning messages generated.
2480
2481
2482 .. index:: -gnatl=fname (gcc)
2483
2484 :switch:`-gnatl={fname}`
2485 This has the same effect as :switch:`-gnatl` except that the output is
2486 written to a file instead of to standard output. If the given name
2487 :file:`fname` does not start with a period, then it is the full name
2488 of the file to be written. If :file:`fname` is an extension, it is
2489 appended to the name of the file being compiled. For example, if
2490 file :file:`xyz.adb` is compiled with :switch:`-gnatl=.lst`,
2491 then the output is written to file xyz.adb.lst.
2492
2493
2494 .. index:: -gnatU (gcc)
2495
2496 :switch:`-gnatU`
2497 This switch forces all error messages to be preceded by the unique
2498 string 'error:'. This means that error messages take a few more
2499 characters in space, but allows easy searching for and identification
2500 of error messages.
2501
2502
2503 .. index:: -gnatb (gcc)
2504
2505 :switch:`-gnatb`
2506 The ``b`` stands for brief.
2507 This switch causes GNAT to generate the
2508 brief format error messages to :file:`stderr` (the standard error
2509 file) as well as the verbose
2510 format message or full listing (which as usual is written to
2511 :file:`stdout`, the standard output file).
2512
2513
2514 .. index:: -gnatm (gcc)
2515
2516 :switch:`-gnatm={n}`
2517 The ``m`` stands for maximum.
2518 ``n`` is a decimal integer in the
2519 range of 1 to 999999 and limits the number of error or warning
2520 messages to be generated. For example, using
2521 :switch:`-gnatm2` might yield
2522
2523 ::
2524
2525 e.adb:3:04: Incorrect spelling of keyword "function"
2526 e.adb:5:35: missing ".."
2527 fatal error: maximum number of errors detected
2528 compilation abandoned
2529
2530
2531 The default setting if
2532 no switch is given is 9999. If the number of warnings reaches this
2533 limit, then a message is output and further warnings are suppressed,
2534 but the compilation is continued. If the number of error messages
2535 reaches this limit, then a message is output and the compilation
2536 is abandoned. A value of zero means that no limit applies.
2537
2538 Note that the equal sign is optional, so the switches
2539 :switch:`-gnatm2` and :switch:`-gnatm=2` are equivalent.
2540
2541
2542 .. index:: -gnatf (gcc)
2543
2544 :switch:`-gnatf`
2545 .. index:: Error messages, suppressing
2546
2547 The ``f`` stands for full.
2548 Normally, the compiler suppresses error messages that are likely to be
2549 redundant. This switch causes all error
2550 messages to be generated. In particular, in the case of
2551 references to undefined variables. If a given variable is referenced
2552 several times, the normal format of messages is
2553
2554 ::
2555
2556 e.adb:7:07: "V" is undefined (more references follow)
2557
2558 where the parenthetical comment warns that there are additional
2559 references to the variable ``V``. Compiling the same program with the
2560 :switch:`-gnatf` switch yields
2561
2562 ::
2563
2564 e.adb:7:07: "V" is undefined
2565 e.adb:8:07: "V" is undefined
2566 e.adb:8:12: "V" is undefined
2567 e.adb:8:16: "V" is undefined
2568 e.adb:9:07: "V" is undefined
2569 e.adb:9:12: "V" is undefined
2570
2571 The :switch:`-gnatf` switch also generates additional information for
2572 some error messages. Some examples are:
2573
2574 * Details on possibly non-portable unchecked conversion
2575
2576 * List possible interpretations for ambiguous calls
2577
2578 * Additional details on incorrect parameters
2579
2580
2581 .. index:: -gnatjnn (gcc)
2582
2583 :switch:`-gnatjnn`
2584 In normal operation mode (or if :switch:`-gnatj0` is used), then error messages
2585 with continuation lines are treated as though the continuation lines were
2586 separate messages (and so a warning with two continuation lines counts as
2587 three warnings, and is listed as three separate messages).
2588
2589 If the :switch:`-gnatjnn` switch is used with a positive value for nn, then
2590 messages are output in a different manner. A message and all its continuation
2591 lines are treated as a unit, and count as only one warning or message in the
2592 statistics totals. Furthermore, the message is reformatted so that no line
2593 is longer than nn characters.
2594
2595
2596 .. index:: -gnatq (gcc)
2597
2598 :switch:`-gnatq`
2599 The ``q`` stands for quit (really 'don't quit').
2600 In normal operation mode, the compiler first parses the program and
2601 determines if there are any syntax errors. If there are, appropriate
2602 error messages are generated and compilation is immediately terminated.
2603 This switch tells
2604 GNAT to continue with semantic analysis even if syntax errors have been
2605 found. This may enable the detection of more errors in a single run. On
2606 the other hand, the semantic analyzer is more likely to encounter some
2607 internal fatal error when given a syntactically invalid tree.
2608
2609
2610 .. index:: -gnatQ (gcc)
2611
2612 :switch:`-gnatQ`
2613 In normal operation mode, the :file:`ALI` file is not generated if any
2614 illegalities are detected in the program. The use of :switch:`-gnatQ` forces
2615 generation of the :file:`ALI` file. This file is marked as being in
2616 error, so it cannot be used for binding purposes, but it does contain
2617 reasonably complete cross-reference information, and thus may be useful
2618 for use by tools (e.g., semantic browsing tools or integrated development
2619 environments) that are driven from the :file:`ALI` file. This switch
2620 implies :switch:`-gnatq`, since the semantic phase must be run to get a
2621 meaningful ALI file.
2622
2623 When :switch:`-gnatQ` is used and the generated :file:`ALI` file is marked as
2624 being in error, ``gnatmake`` will attempt to recompile the source when it
2625 finds such an :file:`ALI` file, including with switch :switch:`-gnatc`.
2626
2627 Note that :switch:`-gnatQ` has no effect if :switch:`-gnats` is specified,
2628 since ALI files are never generated if :switch:`-gnats` is set.
2629
2630
2631 .. _Warning_Message_Control:
2632
2633 Warning Message Control
2634 -----------------------
2635
2636 .. index:: Warning messages
2637
2638 In addition to error messages, which correspond to illegalities as defined
2639 in the Ada Reference Manual, the compiler detects two kinds of warning
2640 situations.
2641
2642 First, the compiler considers some constructs suspicious and generates a
2643 warning message to alert you to a possible error. Second, if the
2644 compiler detects a situation that is sure to raise an exception at
2645 run time, it generates a warning message. The following shows an example
2646 of warning messages:
2647
2648 ::
2649
2650 e.adb:4:24: warning: creation of object may raise Storage_Error
2651 e.adb:10:17: warning: static value out of range
2652 e.adb:10:17: warning: "Constraint_Error" will be raised at run time
2653
2654
2655 GNAT considers a large number of situations as appropriate
2656 for the generation of warning messages. As always, warnings are not
2657 definite indications of errors. For example, if you do an out-of-range
2658 assignment with the deliberate intention of raising a
2659 ``Constraint_Error`` exception, then the warning that may be
2660 issued does not indicate an error. Some of the situations for which GNAT
2661 issues warnings (at least some of the time) are given in the following
2662 list. This list is not complete, and new warnings are often added to
2663 subsequent versions of GNAT. The list is intended to give a general idea
2664 of the kinds of warnings that are generated.
2665
2666 * Possible infinitely recursive calls
2667
2668 * Out-of-range values being assigned
2669
2670 * Possible order of elaboration problems
2671
2672 * Size not a multiple of alignment for a record type
2673
2674 * Assertions (pragma Assert) that are sure to fail
2675
2676 * Unreachable code
2677
2678 * Address clauses with possibly unaligned values, or where an attempt is
2679 made to overlay a smaller variable with a larger one.
2680
2681 * Fixed-point type declarations with a null range
2682
2683 * Direct_IO or Sequential_IO instantiated with a type that has access values
2684
2685 * Variables that are never assigned a value
2686
2687 * Variables that are referenced before being initialized
2688
2689 * Task entries with no corresponding ``accept`` statement
2690
2691 * Duplicate accepts for the same task entry in a ``select``
2692
2693 * Objects that take too much storage
2694
2695 * Unchecked conversion between types of differing sizes
2696
2697 * Missing ``return`` statement along some execution path in a function
2698
2699 * Incorrect (unrecognized) pragmas
2700
2701 * Incorrect external names
2702
2703 * Allocation from empty storage pool
2704
2705 * Potentially blocking operation in protected type
2706
2707 * Suspicious parenthesization of expressions
2708
2709 * Mismatching bounds in an aggregate
2710
2711 * Attempt to return local value by reference
2712
2713 * Premature instantiation of a generic body
2714
2715 * Attempt to pack aliased components
2716
2717 * Out of bounds array subscripts
2718
2719 * Wrong length on string assignment
2720
2721 * Violations of style rules if style checking is enabled
2722
2723 * Unused |with| clauses
2724
2725 * ``Bit_Order`` usage that does not have any effect
2726
2727 * ``Standard.Duration`` used to resolve universal fixed expression
2728
2729 * Dereference of possibly null value
2730
2731 * Declaration that is likely to cause storage error
2732
2733 * Internal GNAT unit |withed| by application unit
2734
2735 * Values known to be out of range at compile time
2736
2737 * Unreferenced or unmodified variables. Note that a special
2738 exemption applies to variables which contain any of the substrings
2739 ``DISCARD, DUMMY, IGNORE, JUNK, UNUSED``, in any casing. Such variables
2740 are considered likely to be intentionally used in a situation where
2741 otherwise a warning would be given, so warnings of this kind are
2742 always suppressed for such variables.
2743
2744 * Address overlays that could clobber memory
2745
2746 * Unexpected initialization when address clause present
2747
2748 * Bad alignment for address clause
2749
2750 * Useless type conversions
2751
2752 * Redundant assignment statements and other redundant constructs
2753
2754 * Useless exception handlers
2755
2756 * Accidental hiding of name by child unit
2757
2758 * Access before elaboration detected at compile time
2759
2760 * A range in a ``for`` loop that is known to be null or might be null
2761
2762
2763 The following section lists compiler switches that are available
2764 to control the handling of warning messages. It is also possible
2765 to exercise much finer control over what warnings are issued and
2766 suppressed using the GNAT pragma Warnings (see the description
2767 of the pragma in the :title:`GNAT_Reference_manual`).
2768
2769
2770 .. index:: -gnatwa (gcc)
2771
2772 :switch:`-gnatwa`
2773 *Activate most optional warnings.*
2774
2775 This switch activates most optional warning messages. See the remaining list
2776 in this section for details on optional warning messages that can be
2777 individually controlled. The warnings that are not turned on by this
2778 switch are:
2779
2780
2781 * :switch:`-gnatwd` (implicit dereferencing)
2782
2783 * :switch:`-gnatw.d` (tag warnings with -gnatw switch)
2784
2785 * :switch:`-gnatwh` (hiding)
2786
2787 * :switch:`-gnatw.h` (holes in record layouts)
2788
2789 * :switch:`-gnatw.j` (late primitives of tagged types)
2790
2791 * :switch:`-gnatw.k` (redefinition of names in standard)
2792
2793 * :switch:`-gnatwl` (elaboration warnings)
2794
2795 * :switch:`-gnatw.l` (inherited aspects)
2796
2797 * :switch:`-gnatw.n` (atomic synchronization)
2798
2799 * :switch:`-gnatwo` (address clause overlay)
2800
2801 * :switch:`-gnatw.o` (values set by out parameters ignored)
2802
2803 * :switch:`-gnatw.q` (questionable layout of record types)
2804
2805 * :switch:`-gnatw_q` (ignored equality)
2806
2807 * :switch:`-gnatw_r` (out-of-order record representation clauses)
2808
2809 * :switch:`-gnatw.s` (overridden size clause)
2810
2811 * :switch:`-gnatw_s` (ineffective predicate test)
2812
2813 * :switch:`-gnatwt` (tracking of deleted conditional code)
2814
2815 * :switch:`-gnatw.u` (unordered enumeration)
2816
2817 * :switch:`-gnatw.w` (use of Warnings Off)
2818
2819 * :switch:`-gnatw.y` (reasons for package needing body)
2820
2821 All other optional warnings are turned on.
2822
2823
2824 .. index:: -gnatwA (gcc)
2825
2826 :switch:`-gnatwA`
2827 *Suppress all optional errors.*
2828
2829 This switch suppresses all optional warning messages, see remaining list
2830 in this section for details on optional warning messages that can be
2831 individually controlled. Note that unlike switch :switch:`-gnatws`, the
2832 use of switch :switch:`-gnatwA` does not suppress warnings that are
2833 normally given unconditionally and cannot be individually controlled
2834 (for example, the warning about a missing exit path in a function).
2835 Also, again unlike switch :switch:`-gnatws`, warnings suppressed by
2836 the use of switch :switch:`-gnatwA` can be individually turned back
2837 on. For example the use of switch :switch:`-gnatwA` followed by
2838 switch :switch:`-gnatwd` will suppress all optional warnings except
2839 the warnings for implicit dereferencing.
2840
2841 .. index:: -gnatw.a (gcc)
2842
2843 :switch:`-gnatw.a`
2844 *Activate warnings on failing assertions.*
2845
2846 .. index:: Assert failures
2847
2848 This switch activates warnings for assertions where the compiler can tell at
2849 compile time that the assertion will fail. Note that this warning is given
2850 even if assertions are disabled. The default is that such warnings are
2851 generated.
2852
2853
2854 .. index:: -gnatw.A (gcc)
2855
2856 :switch:`-gnatw.A`
2857 *Suppress warnings on failing assertions.*
2858
2859 .. index:: Assert failures
2860
2861 This switch suppresses warnings for assertions where the compiler can tell at
2862 compile time that the assertion will fail.
2863
2864
2865 .. index:: -gnatw_a
2866
2867 :switch:`-gnatw_a`
2868 *Activate warnings on anonymous allocators.*
2869
2870 .. index:: Anonymous allocators
2871
2872 This switch activates warnings for allocators of anonymous access types,
2873 which can involve run-time accessibility checks and lead to unexpected
2874 accessibility violations. For more details on the rules involved, see
2875 RM 3.10.2 (14).
2876
2877
2878 .. index:: -gnatw_A
2879
2880 :switch:`-gnatw_A`
2881 *Suppress warnings on anonymous allocators.*
2882
2883 .. index:: Anonymous allocators
2884
2885 This switch suppresses warnings for anonymous access type allocators.
2886
2887
2888 .. index:: -gnatwb (gcc)
2889
2890 :switch:`-gnatwb`
2891 *Activate warnings on bad fixed values.*
2892
2893 .. index:: Bad fixed values
2894
2895 .. index:: Fixed-point Small value
2896
2897 .. index:: Small value
2898
2899 This switch activates warnings for static fixed-point expressions whose
2900 value is not an exact multiple of Small. Such values are implementation
2901 dependent, since an implementation is free to choose either of the multiples
2902 that surround the value. GNAT always chooses the closer one, but this is not
2903 required behavior, and it is better to specify a value that is an exact
2904 multiple, ensuring predictable execution. The default is that such warnings
2905 are not generated.
2906
2907
2908 .. index:: -gnatwB (gcc)
2909
2910 :switch:`-gnatwB`
2911 *Suppress warnings on bad fixed values.*
2912
2913 This switch suppresses warnings for static fixed-point expressions whose
2914 value is not an exact multiple of Small.
2915
2916
2917 .. index:: -gnatw.b (gcc)
2918
2919 :switch:`-gnatw.b`
2920 *Activate warnings on biased representation.*
2921
2922 .. index:: Biased representation
2923
2924 This switch activates warnings when a size clause, value size clause, component
2925 clause, or component size clause forces the use of biased representation for an
2926 integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
2927 to represent 10/11). The default is that such warnings are generated.
2928
2929
2930 .. index:: -gnatwB (gcc)
2931
2932 :switch:`-gnatw.B`
2933 *Suppress warnings on biased representation.*
2934
2935 This switch suppresses warnings for representation clauses that force the use
2936 of biased representation.
2937
2938
2939 .. index:: -gnatwc (gcc)
2940
2941 :switch:`-gnatwc`
2942 *Activate warnings on conditionals.*
2943
2944 .. index:: Conditionals, constant
2945
2946 This switch activates warnings for boolean expressions that are known to
2947 be True or False at compile time. The default
2948 is that such warnings are not generated.
2949 Note that this warning does
2950 not get issued for the use of boolean constants whose
2951 values are known at compile time, since this is a standard technique
2952 for conditional compilation in Ada, and this would generate too many
2953 false positive warnings.
2954
2955 This warning option also activates a special test for comparisons using
2956 the operators '>=' and' <='.
2957 If the compiler can tell that only the equality condition is possible,
2958 then it will warn that the '>' or '<' part of the test
2959 is useless and that the operator could be replaced by '='.
2960 An example would be comparing a ``Natural`` variable <= 0.
2961
2962 This warning option also generates warnings if
2963 one or both tests is optimized away in a membership test for integer
2964 values if the result can be determined at compile time. Range tests on
2965 enumeration types are not included, since it is common for such tests
2966 to include an end point.
2967
2968 This warning can also be turned on using :switch:`-gnatwa`.
2969
2970
2971 .. index:: -gnatwC (gcc)
2972
2973 :switch:`-gnatwC`
2974 *Suppress warnings on conditionals.*
2975
2976 This switch suppresses warnings for conditional expressions used in
2977 tests that are known to be True or False at compile time.
2978
2979
2980 .. index:: -gnatw.c (gcc)
2981
2982 :switch:`-gnatw.c`
2983 *Activate warnings on missing component clauses.*
2984
2985 .. index:: Component clause, missing
2986
2987 This switch activates warnings for record components where a record
2988 representation clause is present and has component clauses for the
2989 majority, but not all, of the components. A warning is given for each
2990 component for which no component clause is present.
2991
2992
2993 .. index:: -gnatw.C (gcc)
2994
2995 :switch:`-gnatw.C`
2996 *Suppress warnings on missing component clauses.*
2997
2998 This switch suppresses warnings for record components that are
2999 missing a component clause in the situation described above.
3000
3001
3002 .. index:: -gnatw_c (gcc)
3003
3004 :switch:`-gnatw_c`
3005 *Activate warnings on unknown condition in Compile_Time_Warning.*
3006
3007 .. index:: Compile_Time_Warning
3008 .. index:: Compile_Time_Error
3009
3010 This switch activates warnings on a pragma Compile_Time_Warning
3011 or Compile_Time_Error whose condition has a value that is not
3012 known at compile time.
3013 The default is that such warnings are generated.
3014
3015
3016 .. index:: -gnatw_C (gcc)
3017
3018 :switch:`-gnatw_C`
3019 *Suppress warnings on unknown condition in Compile_Time_Warning.*
3020
3021 This switch suppresses warnings on a pragma Compile_Time_Warning
3022 or Compile_Time_Error whose condition has a value that is not
3023 known at compile time.
3024
3025
3026 .. index:: -gnatwd (gcc)
3027
3028 :switch:`-gnatwd`
3029 *Activate warnings on implicit dereferencing.*
3030
3031 If this switch is set, then the use of a prefix of an access type
3032 in an indexed component, slice, or selected component without an
3033 explicit ``.all`` will generate a warning. With this warning
3034 enabled, access checks occur only at points where an explicit
3035 ``.all`` appears in the source code (assuming no warnings are
3036 generated as a result of this switch). The default is that such
3037 warnings are not generated.
3038
3039
3040 .. index:: -gnatwD (gcc)
3041
3042 :switch:`-gnatwD`
3043 *Suppress warnings on implicit dereferencing.*
3044
3045 .. index:: Implicit dereferencing
3046
3047 .. index:: Dereferencing, implicit
3048
3049 This switch suppresses warnings for implicit dereferences in
3050 indexed components, slices, and selected components.
3051
3052
3053 .. index:: -gnatw.d (gcc)
3054
3055 :switch:`-gnatw.d`
3056 *Activate tagging of warning and info messages.*
3057
3058 If this switch is set, then warning messages are tagged, with one of the
3059 following strings:
3060
3061 - *[-gnatw?]*
3062 Used to tag warnings controlled by the switch :switch:`-gnatwx` where x
3063 is a letter a-z.
3064
3065
3066 - *[-gnatw.?]*
3067 Used to tag warnings controlled by the switch :switch:`-gnatw.x` where x
3068 is a letter a-z.
3069
3070
3071 - *[-gnatel]*
3072 Used to tag elaboration information (info) messages generated when the
3073 static model of elaboration is used and the :switch:`-gnatel` switch is set.
3074
3075
3076 - *[restriction warning]*
3077 Used to tag warning messages for restriction violations, activated by use
3078 of the pragma ``Restriction_Warnings``.
3079
3080
3081 - *[warning-as-error]*
3082 Used to tag warning messages that have been converted to error messages by
3083 use of the pragma Warning_As_Error. Note that such warnings are prefixed by
3084 the string "error: " rather than "warning: ".
3085
3086
3087 - *[enabled by default]*
3088 Used to tag all other warnings that are always given by default, unless
3089 warnings are completely suppressed using pragma *Warnings(Off)* or
3090 the switch :switch:`-gnatws`.
3091
3092
3093
3094 .. index:: -gnatw.d (gcc)
3095
3096 :switch:`-gnatw.D`
3097 *Deactivate tagging of warning and info messages messages.*
3098
3099 If this switch is set, then warning messages return to the default
3100 mode in which warnings and info messages are not tagged as described above for
3101 :switch:`-gnatw.d`.
3102
3103
3104 .. index:: -gnatwe (gcc)
3105 .. index:: Warnings, treat as error
3106
3107 :switch:`-gnatwe`
3108 *Treat warnings and style checks as errors.*
3109
3110 This switch causes warning messages and style check messages to be
3111 treated as errors.
3112 The warning string still appears, but the warning messages are counted
3113 as errors, and prevent the generation of an object file. Note that this
3114 is the only -gnatw switch that affects the handling of style check messages.
3115 Note also that this switch has no effect on info (information) messages, which
3116 are not treated as errors if this switch is present.
3117
3118
3119 .. index:: -gnatw.e (gcc)
3120
3121 :switch:`-gnatw.e`
3122 *Activate every optional warning.*
3123
3124 .. index:: Warnings, activate every optional warning
3125
3126 This switch activates all optional warnings, including those which
3127 are not activated by :switch:`-gnatwa`. The use of this switch is not
3128 recommended for normal use. If you turn this switch on, it is almost
3129 certain that you will get large numbers of useless warnings. The
3130 warnings that are excluded from :switch:`-gnatwa` are typically highly
3131 specialized warnings that are suitable for use only in code that has
3132 been specifically designed according to specialized coding rules.
3133
3134
3135 .. index:: -gnatwE (gcc)
3136 .. index:: Warnings, treat as error
3137
3138 :switch:`-gnatwE`
3139 *Treat all run-time exception warnings as errors.*
3140
3141 This switch causes warning messages regarding errors that will be raised
3142 during run-time execution to be treated as errors.
3143
3144
3145 .. index:: -gnatwf (gcc)
3146
3147 :switch:`-gnatwf`
3148 *Activate warnings on unreferenced formals.*
3149
3150 .. index:: Formals, unreferenced
3151
3152 This switch causes a warning to be generated if a formal parameter
3153 is not referenced in the body of the subprogram. This warning can
3154 also be turned on using :switch:`-gnatwu`. The
3155 default is that these warnings are not generated.
3156
3157
3158 .. index:: -gnatwF (gcc)
3159
3160 :switch:`-gnatwF`
3161 *Suppress warnings on unreferenced formals.*
3162
3163 This switch suppresses warnings for unreferenced formal
3164 parameters. Note that the
3165 combination :switch:`-gnatwu` followed by :switch:`-gnatwF` has the
3166 effect of warning on unreferenced entities other than subprogram
3167 formals.
3168
3169
3170 .. index:: -gnatwg (gcc)
3171
3172 :switch:`-gnatwg`
3173 *Activate warnings on unrecognized pragmas.*
3174
3175 .. index:: Pragmas, unrecognized
3176
3177 This switch causes a warning to be generated if an unrecognized
3178 pragma is encountered. Apart from issuing this warning, the
3179 pragma is ignored and has no effect. The default
3180 is that such warnings are issued (satisfying the Ada Reference
3181 Manual requirement that such warnings appear).
3182
3183
3184 .. index:: -gnatwG (gcc)
3185
3186 :switch:`-gnatwG`
3187 *Suppress warnings on unrecognized pragmas.*
3188
3189 This switch suppresses warnings for unrecognized pragmas.
3190
3191
3192 .. index:: -gnatw.g (gcc)
3193
3194 :switch:`-gnatw.g`
3195 *Warnings used for GNAT sources.*
3196
3197 This switch sets the warning categories that are used by the standard
3198 GNAT style. Currently this is equivalent to
3199 :switch:`-gnatwAao.q.s.CI.V.X.Z`
3200 but more warnings may be added in the future without advanced notice.
3201
3202
3203 .. index:: -gnatwh (gcc)
3204
3205 :switch:`-gnatwh`
3206 *Activate warnings on hiding.*
3207
3208 .. index:: Hiding of Declarations
3209
3210 This switch activates warnings on hiding declarations that are considered
3211 potentially confusing. Not all cases of hiding cause warnings; for example an
3212 overriding declaration hides an implicit declaration, which is just normal
3213 code. The default is that warnings on hiding are not generated.
3214
3215
3216 .. index:: -gnatwH (gcc)
3217
3218 :switch:`-gnatwH`
3219 *Suppress warnings on hiding.*
3220
3221 This switch suppresses warnings on hiding declarations.
3222
3223
3224 .. index:: -gnatw.h (gcc)
3225
3226 :switch:`-gnatw.h`
3227 *Activate warnings on holes/gaps in records.*
3228
3229 .. index:: Record Representation (gaps)
3230
3231 This switch activates warnings on component clauses in record
3232 representation clauses that leave holes (gaps) in the record layout.
3233 If a record representation clause does not specify a location for
3234 every component of the record type, then the warnings generated (or not
3235 generated) are unspecified. For example, there may be gaps for which
3236 either no warning is generated or a warning is generated that
3237 incorrectly describes the location of the gap. This undesirable situation
3238 can sometimes be avoided by adding (and specifying the location for) unused
3239 fill fields.
3240
3241
3242 .. index:: -gnatw.H (gcc)
3243
3244 :switch:`-gnatw.H`
3245 *Suppress warnings on holes/gaps in records.*
3246
3247 This switch suppresses warnings on component clauses in record
3248 representation clauses that leave holes (haps) in the record layout.
3249
3250
3251 .. index:: -gnatwi (gcc)
3252
3253 :switch:`-gnatwi`
3254 *Activate warnings on implementation units.*
3255
3256 This switch activates warnings for a |with| of an internal GNAT
3257 implementation unit, defined as any unit from the ``Ada``,
3258 ``Interfaces``, ``GNAT``,
3259 or ``System``
3260 hierarchies that is not
3261 documented in either the Ada Reference Manual or the GNAT
3262 Programmer's Reference Manual. Such units are intended only
3263 for internal implementation purposes and should not be |withed|
3264 by user programs. The default is that such warnings are generated
3265
3266
3267 .. index:: -gnatwI (gcc)
3268
3269 :switch:`-gnatwI`
3270 *Disable warnings on implementation units.*
3271
3272 This switch disables warnings for a |with| of an internal GNAT
3273 implementation unit.
3274
3275
3276 .. index:: -gnatw.i (gcc)
3277
3278 :switch:`-gnatw.i`
3279 *Activate warnings on overlapping actuals.*
3280
3281 This switch enables a warning on statically detectable overlapping actuals in
3282 a subprogram call, when one of the actuals is an in-out parameter, and the
3283 types of the actuals are not by-copy types. This warning is off by default.
3284
3285
3286 .. index:: -gnatw.I (gcc)
3287
3288 :switch:`-gnatw.I`
3289 *Disable warnings on overlapping actuals.*
3290
3291 This switch disables warnings on overlapping actuals in a call.
3292
3293
3294 .. index:: -gnatwj (gcc)
3295
3296 :switch:`-gnatwj`
3297 *Activate warnings on obsolescent features (Annex J).*
3298
3299 .. index:: Features, obsolescent
3300
3301 .. index:: Obsolescent features
3302
3303 If this warning option is activated, then warnings are generated for
3304 calls to subprograms marked with ``pragma Obsolescent`` and
3305 for use of features in Annex J of the Ada Reference Manual. In the
3306 case of Annex J, not all features are flagged. In particular, uses of package
3307 ``ASCII`` are not flagged, since these are very common and
3308 would generate many annoying positive warnings. The default is that
3309 such warnings are not generated.
3310
3311 In addition to the above cases, warnings are also generated for
3312 GNAT features that have been provided in past versions but which
3313 have been superseded (typically by features in the new Ada standard).
3314 For example, ``pragma Ravenscar`` will be flagged since its
3315 function is replaced by ``pragma Profile(Ravenscar)``, and
3316 ``pragma Interface_Name`` will be flagged since its function
3317 is replaced by ``pragma Import``.
3318
3319 Note that this warning option functions differently from the
3320 restriction ``No_Obsolescent_Features`` in two respects.
3321 First, the restriction applies only to annex J features.
3322 Second, the restriction does flag uses of package ``ASCII``.
3323
3324
3325 .. index:: -gnatwJ (gcc)
3326
3327 :switch:`-gnatwJ`
3328 *Suppress warnings on obsolescent features (Annex J).*
3329
3330 This switch disables warnings on use of obsolescent features.
3331
3332
3333 .. index:: -gnatw.j (gcc)
3334
3335 :switch:`-gnatw.j`
3336 *Activate warnings on late declarations of tagged type primitives.*
3337
3338 This switch activates warnings on visible primitives added to a
3339 tagged type after deriving a private extension from it.
3340
3341
3342 .. index:: -gnatw.J (gcc)
3343
3344 :switch:`-gnatw.J`
3345 *Suppress warnings on late declarations of tagged type primitives.*
3346
3347 This switch suppresses warnings on visible primitives added to a
3348 tagged type after deriving a private extension from it.
3349
3350
3351 .. index:: -gnatwk (gcc)
3352
3353 :switch:`-gnatwk`
3354 *Activate warnings on variables that could be constants.*
3355
3356 This switch activates warnings for variables that are initialized but
3357 never modified, and then could be declared constants. The default is that
3358 such warnings are not given.
3359
3360
3361 .. index:: -gnatwK (gcc)
3362
3363 :switch:`-gnatwK`
3364 *Suppress warnings on variables that could be constants.*
3365
3366 This switch disables warnings on variables that could be declared constants.
3367
3368
3369 .. index:: -gnatw.k (gcc)
3370
3371 :switch:`-gnatw.k`
3372 *Activate warnings on redefinition of names in standard.*
3373
3374 This switch activates warnings for declarations that declare a name that
3375 is defined in package Standard. Such declarations can be confusing,
3376 especially since the names in package Standard continue to be directly
3377 visible, meaning that use visibility on such redeclared names does not
3378 work as expected. Names of discriminants and components in records are
3379 not included in this check.
3380
3381
3382 .. index:: -gnatwK (gcc)
3383
3384 :switch:`-gnatw.K`
3385 *Suppress warnings on redefinition of names in standard.*
3386
3387 This switch disables warnings for declarations that declare a name that
3388 is defined in package Standard.
3389
3390
3391 .. index:: -gnatwl (gcc)
3392
3393 :switch:`-gnatwl`
3394 *Activate warnings for elaboration pragmas.*
3395
3396 .. index:: Elaboration, warnings
3397
3398 This switch activates warnings for possible elaboration problems,
3399 including suspicious use
3400 of ``Elaborate`` pragmas, when using the static elaboration model, and
3401 possible situations that may raise ``Program_Error`` when using the
3402 dynamic elaboration model.
3403 See the section in this guide on elaboration checking for further details.
3404 The default is that such warnings
3405 are not generated.
3406
3407
3408 .. index:: -gnatwL (gcc)
3409
3410 :switch:`-gnatwL`
3411 *Suppress warnings for elaboration pragmas.*
3412
3413 This switch suppresses warnings for possible elaboration problems.
3414
3415
3416 .. index:: -gnatw.l (gcc)
3417
3418 :switch:`-gnatw.l`
3419 *List inherited aspects as info messages.*
3420
3421 This switch causes the compiler to list inherited invariants,
3422 preconditions, and postconditions from Type_Invariant'Class, Invariant'Class,
3423 Pre'Class, and Post'Class aspects. Also list inherited subtype predicates.
3424
3425
3426 .. index:: -gnatw.L (gcc)
3427
3428 :switch:`-gnatw.L`
3429 *Suppress listing of inherited aspects as info messages.*
3430
3431 This switch suppresses listing of inherited aspects.
3432
3433
3434 .. index:: -gnatw_l (gcc)
3435
3436 :switch:`-gnatw_l`
3437 *Activate warnings on implicitly limited types.*
3438
3439 This switch causes the compiler trigger warnings on record types that do not
3440 have a limited keyword but contain a component that is a limited type.
3441
3442
3443 .. index:: -gnatw_L (gcc)
3444
3445 :switch:`-gnatw_L`
3446 *Suppress warnings on implicitly limited types.*
3447
3448 This switch suppresses warnings on implicitly limited types.
3449
3450
3451 .. index:: -gnatwm (gcc)
3452
3453 :switch:`-gnatwm`
3454 *Activate warnings on modified but unreferenced variables.*
3455
3456 This switch activates warnings for variables that are assigned (using
3457 an initialization value or with one or more assignment statements) but
3458 whose value is never read. The warning is suppressed for volatile
3459 variables and also for variables that are renamings of other variables
3460 or for which an address clause is given.
3461 The default is that these warnings are not given.
3462
3463
3464 .. index:: -gnatwM (gcc)
3465
3466 :switch:`-gnatwM`
3467 *Disable warnings on modified but unreferenced variables.*
3468
3469 This switch disables warnings for variables that are assigned or
3470 initialized, but never read.
3471
3472
3473 .. index:: -gnatw.m (gcc)
3474
3475 :switch:`-gnatw.m`
3476 *Activate warnings on suspicious modulus values.*
3477
3478 This switch activates warnings for modulus values that seem suspicious.
3479 The cases caught are where the size is the same as the modulus (e.g.
3480 a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
3481 with no size clause. The guess in both cases is that 2**x was intended
3482 rather than x. In addition expressions of the form 2*x for small x
3483 generate a warning (the almost certainly accurate guess being that
3484 2**x was intended). This switch also activates warnings for negative
3485 literal values of a modular type, which are interpreted as large positive
3486 integers after wrap-around. The default is that these warnings are given.
3487
3488
3489
3490 .. index:: -gnatw.M (gcc)
3491
3492 :switch:`-gnatw.M`
3493 *Disable warnings on suspicious modulus values.*
3494
3495 This switch disables warnings for suspicious modulus values.
3496
3497
3498 .. index:: -gnatwn (gcc)
3499
3500 :switch:`-gnatwn`
3501 *Set normal warnings mode.*
3502
3503 This switch sets normal warning mode, in which enabled warnings are
3504 issued and treated as warnings rather than errors. This is the default
3505 mode. the switch :switch:`-gnatwn` can be used to cancel the effect of
3506 an explicit :switch:`-gnatws` or
3507 :switch:`-gnatwe`. It also cancels the effect of the
3508 implicit :switch:`-gnatwe` that is activated by the
3509 use of :switch:`-gnatg`.
3510
3511
3512 .. index:: -gnatw.n (gcc)
3513 .. index:: Atomic Synchronization, warnings
3514
3515 :switch:`-gnatw.n`
3516 *Activate warnings on atomic synchronization.*
3517
3518 This switch activates warnings when an access to an atomic variable
3519 requires the generation of atomic synchronization code. These
3520 warnings are off by default.
3521
3522 .. index:: -gnatw.N (gcc)
3523
3524 :switch:`-gnatw.N`
3525 *Suppress warnings on atomic synchronization.*
3526
3527 .. index:: Atomic Synchronization, warnings
3528
3529 This switch suppresses warnings when an access to an atomic variable
3530 requires the generation of atomic synchronization code.
3531
3532
3533 .. index:: -gnatwo (gcc)
3534 .. index:: Address Clauses, warnings
3535
3536 :switch:`-gnatwo`
3537 *Activate warnings on address clause overlays.*
3538
3539 This switch activates warnings for possibly unintended initialization
3540 effects of defining address clauses that cause one variable to overlap
3541 another. The default is that such warnings are generated.
3542
3543
3544 .. index:: -gnatwO (gcc)
3545
3546 :switch:`-gnatwO`
3547 *Suppress warnings on address clause overlays.*
3548
3549 This switch suppresses warnings on possibly unintended initialization
3550 effects of defining address clauses that cause one variable to overlap
3551 another.
3552
3553
3554 .. index:: -gnatw.o (gcc)
3555
3556 :switch:`-gnatw.o`
3557 *Activate warnings on modified but unreferenced out parameters.*
3558
3559 This switch activates warnings for variables that are modified by using
3560 them as actuals for a call to a procedure with an out mode formal, where
3561 the resulting assigned value is never read. It is applicable in the case
3562 where there is more than one out mode formal. If there is only one out
3563 mode formal, the warning is issued by default (controlled by -gnatwu).
3564 The warning is suppressed for volatile
3565 variables and also for variables that are renamings of other variables
3566 or for which an address clause is given.
3567 The default is that these warnings are not given.
3568
3569
3570 .. index:: -gnatw.O (gcc)
3571
3572 :switch:`-gnatw.O`
3573 *Disable warnings on modified but unreferenced out parameters.*
3574
3575 This switch suppresses warnings for variables that are modified by using
3576 them as actuals for a call to a procedure with an out mode formal, where
3577 the resulting assigned value is never read.
3578
3579
3580 .. index:: -gnatwp (gcc)
3581 .. index:: Inlining, warnings
3582
3583 :switch:`-gnatwp`
3584 *Activate warnings on ineffective pragma Inlines.*
3585
3586 This switch activates warnings for failure of front end inlining
3587 (activated by :switch:`-gnatN`) to inline a particular call. There are
3588 many reasons for not being able to inline a call, including most
3589 commonly that the call is too complex to inline. The default is
3590 that such warnings are not given.
3591 Warnings on ineffective inlining by the gcc back end can be activated
3592 separately, using the gcc switch -Winline.
3593
3594
3595 .. index:: -gnatwP (gcc)
3596
3597 :switch:`-gnatwP`
3598 *Suppress warnings on ineffective pragma Inlines.*
3599
3600 This switch suppresses warnings on ineffective pragma Inlines. If the
3601 inlining mechanism cannot inline a call, it will simply ignore the
3602 request silently.
3603
3604
3605 .. index:: -gnatw.p (gcc)
3606 .. index:: Parameter order, warnings
3607
3608 :switch:`-gnatw.p`
3609 *Activate warnings on parameter ordering.*
3610
3611 This switch activates warnings for cases of suspicious parameter
3612 ordering when the list of arguments are all simple identifiers that
3613 match the names of the formals, but are in a different order. The
3614 warning is suppressed if any use of named parameter notation is used,
3615 so this is the appropriate way to suppress a false positive (and
3616 serves to emphasize that the "misordering" is deliberate). The
3617 default is that such warnings are not given.
3618
3619
3620 .. index:: -gnatw.P (gcc)
3621
3622 :switch:`-gnatw.P`
3623 *Suppress warnings on parameter ordering.*
3624
3625 This switch suppresses warnings on cases of suspicious parameter
3626 ordering.
3627
3628
3629 .. index:: -gnatw_p (gcc)
3630
3631 :switch:`-gnatw_p`
3632 *Activate warnings for pedantic checks.*
3633
3634 This switch activates warnings for the failure of certain pedantic checks.
3635 The only case currently supported is a check that the subtype_marks given
3636 for corresponding formal parameter and function results in a subprogram
3637 declaration and its body denote the same subtype declaration. The default
3638 is that such warnings are not given.
3639
3640 .. index:: -gnatw_P (gcc)
3641
3642 :switch:`-gnatw_P`
3643 *Suppress warnings for pedantic checks.*
3644
3645 This switch suppresses warnings on violations of pedantic checks.
3646
3647
3648 .. index:: -gnatwq (gcc)
3649 .. index:: Parentheses, warnings
3650
3651 :switch:`-gnatwq`
3652 *Activate warnings on questionable missing parentheses.*
3653
3654 This switch activates warnings for cases where parentheses are not used and
3655 the result is potential ambiguity from a readers point of view. For example
3656 (not a > b) when a and b are modular means ((not a) > b) and very likely the
3657 programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
3658 quite likely ((-x) mod 5) was intended. In such situations it seems best to
3659 follow the rule of always parenthesizing to make the association clear, and
3660 this warning switch warns if such parentheses are not present. The default
3661 is that these warnings are given.
3662
3663
3664 .. index:: -gnatwQ (gcc)
3665
3666 :switch:`-gnatwQ`
3667 *Suppress warnings on questionable missing parentheses.*
3668
3669 This switch suppresses warnings for cases where the association is not
3670 clear and the use of parentheses is preferred.
3671
3672
3673 .. index:: -gnatw.q (gcc)
3674 .. index:: Layout, warnings
3675
3676 :switch:`-gnatw.q`
3677 *Activate warnings on questionable layout of record types.*
3678
3679 This switch activates warnings for cases where the default layout of
3680 a record type, that is to say the layout of its components in textual
3681 order of the source code, would very likely cause inefficiencies in
3682 the code generated by the compiler, both in terms of space and speed
3683 during execution. One warning is issued for each problematic component
3684 without representation clause in the nonvariant part and then in each
3685 variant recursively, if any.
3686
3687 The purpose of these warnings is neither to prescribe an optimal layout
3688 nor to force the use of representation clauses, but rather to get rid of
3689 the most blatant inefficiencies in the layout. Therefore, the default
3690 layout is matched against the following synthetic ordered layout and
3691 the deviations are flagged on a component-by-component basis:
3692
3693 * first all components or groups of components whose length is fixed
3694 and a multiple of the storage unit,
3695
3696 * then the remaining components whose length is fixed and not a multiple
3697 of the storage unit,
3698
3699 * then the remaining components whose length doesn't depend on discriminants
3700 (that is to say, with variable but uniform length for all objects),
3701
3702 * then all components whose length depends on discriminants,
3703
3704 * finally the variant part (if any),
3705
3706 for the nonvariant part and for each variant recursively, if any.
3707
3708 The exact wording of the warning depends on whether the compiler is allowed
3709 to reorder the components in the record type or precluded from doing it by
3710 means of pragma ``No_Component_Reordering``.
3711
3712 The default is that these warnings are not given.
3713
3714 .. index:: -gnatw.Q (gcc)
3715
3716 :switch:`-gnatw.Q`
3717 *Suppress warnings on questionable layout of record types.*
3718
3719 This switch suppresses warnings for cases where the default layout of
3720 a record type would very likely cause inefficiencies.
3721
3722
3723 .. index:: -gnatw_q (gcc)
3724
3725 :switch:`-gnatw_q`
3726 *Activate warnings for ignored equality operators.*
3727
3728 This switch activates warnings for a user-defined "=" function that does
3729 not compose (i.e. is ignored for a predefined "=" for a composite type
3730 containing a component whose type has the user-defined "=" as
3731 primitive). Note that the user-defined "=" must be a primitive operator
3732 in order to trigger the warning.
3733 See RM-4.5.2(14/3-15/5, 21, 24/3, 32.1/1)
3734 for the exact Ada rules on composability of "=".
3735
3736 The default is that these warnings are not given.
3737
3738 .. index:: -gnatw_Q (gcc)
3739
3740 :switch:`-gnatw_Q`
3741 *Suppress warnings for ignored equality operators.*
3742
3743
3744 .. index:: -gnatwr (gcc)
3745
3746 :switch:`-gnatwr`
3747 *Activate warnings on redundant constructs.*
3748
3749 This switch activates warnings for redundant constructs. The following
3750 is the current list of constructs regarded as redundant:
3751
3752 * Assignment of an item to itself.
3753
3754 * Type conversion that converts an expression to its own type.
3755
3756 * Use of the attribute ``Base`` where ``typ'Base`` is the same
3757 as ``typ``.
3758
3759 * Use of pragma ``Pack`` when all components are placed by a record
3760 representation clause.
3761
3762 * Exception handler containing only a reraise statement (raise with no
3763 operand) which has no effect.
3764
3765 * Use of the operator abs on an operand that is known at compile time
3766 to be non-negative
3767
3768 * Comparison of an object or (unary or binary) operation of boolean type to
3769 an explicit True value.
3770
3771 * Import of parent package.
3772
3773 The default is that warnings for redundant constructs are not given.
3774
3775
3776 .. index:: -gnatwR (gcc)
3777
3778 :switch:`-gnatwR`
3779 *Suppress warnings on redundant constructs.*
3780
3781 This switch suppresses warnings for redundant constructs.
3782
3783
3784 .. index:: -gnatw.r (gcc)
3785
3786 :switch:`-gnatw.r`
3787 *Activate warnings for object renaming function.*
3788
3789 This switch activates warnings for an object renaming that renames a
3790 function call, which is equivalent to a constant declaration (as
3791 opposed to renaming the function itself). The default is that these
3792 warnings are given.
3793
3794
3795 .. index:: -gnatw.R (gcc)
3796
3797 :switch:`-gnatw.R`
3798 *Suppress warnings for object renaming function.*
3799
3800 This switch suppresses warnings for object renaming function.
3801
3802
3803 .. index:: -gnatw_r (gcc)
3804
3805 :switch:`-gnatw_r`
3806 *Activate warnings for out-of-order record representation clauses.*
3807
3808 This switch activates warnings for record representation clauses,
3809 if the order of component declarations, component clauses,
3810 and bit-level layout do not all agree.
3811 The default is that these warnings are not given.
3812
3813
3814 .. index:: -gnatw_R (gcc)
3815
3816 :switch:`-gnatw_R`
3817 *Suppress warnings for out-of-order record representation clauses.*
3818
3819
3820 .. index:: -gnatws (gcc)
3821
3822 :switch:`-gnatws`
3823 *Suppress all warnings.*
3824
3825 This switch completely suppresses the
3826 output of all warning messages from the GNAT front end, including
3827 both warnings that can be controlled by switches described in this
3828 section, and those that are normally given unconditionally. The
3829 effect of this suppress action can only be cancelled by a subsequent
3830 use of the switch :switch:`-gnatwn`.
3831
3832 Note that switch :switch:`-gnatws` does not suppress
3833 warnings from the ``gcc`` back end.
3834 To suppress these back end warnings as well, use the switch :switch:`-w`
3835 in addition to :switch:`-gnatws`. Also this switch has no effect on the
3836 handling of style check messages.
3837
3838
3839 .. index:: -gnatw.s (gcc)
3840 .. index:: Record Representation (component sizes)
3841
3842 :switch:`-gnatw.s`
3843 *Activate warnings on overridden size clauses.*
3844
3845 This switch activates warnings on component clauses in record
3846 representation clauses where the length given overrides that
3847 specified by an explicit size clause for the component type. A
3848 warning is similarly given in the array case if a specified
3849 component size overrides an explicit size clause for the array
3850 component type.
3851
3852
3853 .. index:: -gnatw.S (gcc)
3854
3855 :switch:`-gnatw.S`
3856 *Suppress warnings on overridden size clauses.*
3857
3858 This switch suppresses warnings on component clauses in record
3859 representation clauses that override size clauses, and similar
3860 warnings when an array component size overrides a size clause.
3861
3862
3863 .. index:: -gnatw_s (gcc)
3864 .. index:: Warnings
3865
3866 :switch:`-gnatw_s`
3867 *Activate warnings on ineffective predicate tests.*
3868
3869 This switch activates warnings on Static_Predicate aspect
3870 specifications that test for values that do not belong to
3871 the parent subtype. Not all such ineffective tests are detected.
3872
3873 .. index:: -gnatw_S (gcc)
3874
3875 :switch:`-gnatw_S`
3876 *Suppress warnings on ineffective predicate tests.*
3877
3878 This switch suppresses warnings on Static_Predicate aspect
3879 specifications that test for values that do not belong to
3880 the parent subtype.
3881
3882 .. index:: -gnatwt (gcc)
3883 .. index:: Deactivated code, warnings
3884 .. index:: Deleted code, warnings
3885
3886 :switch:`-gnatwt`
3887 *Activate warnings for tracking of deleted conditional code.*
3888
3889 This switch activates warnings for tracking of code in conditionals (IF and
3890 CASE statements) that is detected to be dead code which cannot be executed, and
3891 which is removed by the front end. This warning is off by default. This may be
3892 useful for detecting deactivated code in certified applications.
3893
3894
3895 .. index:: -gnatwT (gcc)
3896
3897 :switch:`-gnatwT`
3898 *Suppress warnings for tracking of deleted conditional code.*
3899
3900 This switch suppresses warnings for tracking of deleted conditional code.
3901
3902
3903 .. index:: -gnatw.t (gcc)
3904
3905 :switch:`-gnatw.t`
3906 *Activate warnings on suspicious contracts.*
3907
3908 This switch activates warnings on suspicious contracts. This includes
3909 warnings on suspicious postconditions (whether a pragma ``Postcondition`` or a
3910 ``Post`` aspect in Ada 2012) and suspicious contract cases (pragma or aspect
3911 ``Contract_Cases``). A function postcondition or contract case is suspicious
3912 when no postcondition or contract case for this function mentions the result
3913 of the function. A procedure postcondition or contract case is suspicious
3914 when it only refers to the pre-state of the procedure, because in that case
3915 it should rather be expressed as a precondition. This switch also controls
3916 warnings on suspicious cases of expressions typically found in contracts like
3917 quantified expressions and uses of Update attribute. The default is that such
3918 warnings are generated.
3919
3920
3921 .. index:: -gnatw.T (gcc)
3922
3923 :switch:`-gnatw.T`
3924 *Suppress warnings on suspicious contracts.*
3925
3926 This switch suppresses warnings on suspicious contracts.
3927
3928
3929 .. index:: -gnatwu (gcc)
3930
3931 :switch:`-gnatwu`
3932 *Activate warnings on unused entities.*
3933
3934 This switch activates warnings to be generated for entities that
3935 are declared but not referenced, and for units that are |withed|
3936 and not
3937 referenced. In the case of packages, a warning is also generated if
3938 no entities in the package are referenced. This means that if a with'ed
3939 package is referenced but the only references are in ``use``
3940 clauses or ``renames``
3941 declarations, a warning is still generated. A warning is also generated
3942 for a generic package that is |withed| but never instantiated.
3943 In the case where a package or subprogram body is compiled, and there
3944 is a |with| on the corresponding spec
3945 that is only referenced in the body,
3946 a warning is also generated, noting that the
3947 |with| can be moved to the body. The default is that
3948 such warnings are not generated.
3949 This switch also activates warnings on unreferenced formals
3950 (it includes the effect of :switch:`-gnatwf`).
3951
3952
3953 .. index:: -gnatwU (gcc)
3954
3955 :switch:`-gnatwU`
3956 *Suppress warnings on unused entities.*
3957
3958 This switch suppresses warnings for unused entities and packages.
3959 It also turns off warnings on unreferenced formals (and thus includes
3960 the effect of :switch:`-gnatwF`).
3961
3962
3963 .. index:: -gnatw.u (gcc)
3964
3965 :switch:`-gnatw.u`
3966 *Activate warnings on unordered enumeration types.*
3967
3968 This switch causes enumeration types to be considered as conceptually
3969 unordered, unless an explicit pragma ``Ordered`` is given for the type.
3970 The effect is to generate warnings in clients that use explicit comparisons
3971 or subranges, since these constructs both treat objects of the type as
3972 ordered. (A *client* is defined as a unit that is other than the unit in
3973 which the type is declared, or its body or subunits.) Please refer to
3974 the description of pragma ``Ordered`` in the
3975 :title:`GNAT Reference Manual` for further details.
3976 The default is that such warnings are not generated.
3977
3978
3979 .. index:: -gnatw.U (gcc)
3980
3981 :switch:`-gnatw.U`
3982 *Deactivate warnings on unordered enumeration types.*
3983
3984 This switch causes all enumeration types to be considered as ordered, so
3985 that no warnings are given for comparisons or subranges for any type.
3986
3987
3988 .. index:: -gnatwv (gcc)
3989 .. index:: Unassigned variable warnings
3990
3991 :switch:`-gnatwv`
3992 *Activate warnings on unassigned variables.*
3993
3994 This switch activates warnings for access to variables which
3995 may not be properly initialized. The default is that
3996 such warnings are generated. This switch will also be emitted when
3997 initializing an array or record object via the following aggregate:
3998
3999 .. code-block:: ada
4000
4001 Array_Or_Record : XXX := (others => <>);
4002
4003 unless the relevant type fully initializes all components.
4004
4005 .. index:: -gnatwV (gcc)
4006
4007 :switch:`-gnatwV`
4008 *Suppress warnings on unassigned variables.*
4009
4010 This switch suppresses warnings for access to variables which
4011 may not be properly initialized.
4012
4013
4014 .. index:: -gnatw.v (gcc)
4015 .. index:: bit order warnings
4016
4017 :switch:`-gnatw.v`
4018 *Activate warnings for non-default bit order.*
4019
4020 This switch activates warning messages about the effects of non-default
4021 bit-order on records to which a component clause is applied. The effect of
4022 specifying non-default bit ordering is a bit subtle
4023 (and changed with Ada 2005), so these messages, which are given by default,
4024 are useful in understanding the exact consequences of using this feature.
4025
4026
4027 .. index:: -gnatw.V (gcc)
4028
4029 :switch:`-gnatw.V`
4030 *Suppress warnings for non-default bit order.*
4031
4032 This switch suppresses warnings for the effects of specifying
4033 non-default bit order on record components with component clauses.
4034
4035
4036 .. index:: -gnatww (gcc)
4037 .. index:: String indexing warnings
4038
4039 :switch:`-gnatww`
4040 *Activate warnings on wrong low bound assumption.*
4041
4042 This switch activates warnings for indexing an unconstrained string parameter
4043 with a literal or S'Length. This is a case where the code is assuming that the
4044 low bound is one, which is in general not true (for example when a slice is
4045 passed). The default is that such warnings are generated.
4046
4047
4048 .. index:: -gnatwW (gcc)
4049
4050 :switch:`-gnatwW`
4051 *Suppress warnings on wrong low bound assumption.*
4052
4053 This switch suppresses warnings for indexing an unconstrained string parameter
4054 with a literal or S'Length. Note that this warning can also be suppressed
4055 in a particular case by adding an assertion that the lower bound is 1,
4056 as shown in the following example:
4057
4058 .. code-block:: ada
4059
4060 procedure K (S : String) is
4061 pragma Assert (S'First = 1);
4062 ...
4063
4064
4065 .. index:: -gnatw.w (gcc)
4066 .. index:: Warnings Off control
4067
4068 :switch:`-gnatw.w`
4069 *Activate warnings on Warnings Off pragmas.*
4070
4071 This switch activates warnings for use of ``pragma Warnings (Off, entity)``
4072 where either the pragma is entirely useless (because it suppresses no
4073 warnings), or it could be replaced by ``pragma Unreferenced`` or
4074 ``pragma Unmodified``.
4075 Also activates warnings for the case of
4076 Warnings (Off, String), where either there is no matching
4077 Warnings (On, String), or the Warnings (Off) did not suppress any warning.
4078 The default is that these warnings are not given.
4079
4080
4081 .. index:: -gnatw.W (gcc)
4082
4083 :switch:`-gnatw.W`
4084 *Suppress warnings on unnecessary Warnings Off pragmas.*
4085
4086 This switch suppresses warnings for use of ``pragma Warnings (Off, ...)``.
4087
4088
4089 .. index:: -gnatwx (gcc)
4090 .. index:: Export/Import pragma warnings
4091
4092 :switch:`-gnatwx`
4093 *Activate warnings on Export/Import pragmas.*
4094
4095 This switch activates warnings on Export/Import pragmas when
4096 the compiler detects a possible conflict between the Ada and
4097 foreign language calling sequences. For example, the use of
4098 default parameters in a convention C procedure is dubious
4099 because the C compiler cannot supply the proper default, so
4100 a warning is issued. The default is that such warnings are
4101 generated.
4102
4103
4104 .. index:: -gnatwX (gcc)
4105
4106 :switch:`-gnatwX`
4107 *Suppress warnings on Export/Import pragmas.*
4108
4109 This switch suppresses warnings on Export/Import pragmas.
4110 The sense of this is that you are telling the compiler that
4111 you know what you are doing in writing the pragma, and it
4112 should not complain at you.
4113
4114
4115 .. index:: -gnatw.x (gcc)
4116
4117 :switch:`-gnatw.x`
4118 *Activate warnings for No_Exception_Propagation mode.*
4119
4120 This switch activates warnings for exception usage when pragma Restrictions
4121 (No_Exception_Propagation) is in effect. Warnings are given for implicit or
4122 explicit exception raises which are not covered by a local handler, and for
4123 exception handlers which do not cover a local raise. The default is that
4124 these warnings are given for units that contain exception handlers.
4125
4126
4127 :switch:`-gnatw.X`
4128 *Disable warnings for No_Exception_Propagation mode.*
4129
4130 This switch disables warnings for exception usage when pragma Restrictions
4131 (No_Exception_Propagation) is in effect.
4132
4133
4134 .. index:: -gnatwy (gcc)
4135 .. index:: Ada compatibility issues warnings
4136
4137 :switch:`-gnatwy`
4138 *Activate warnings for Ada compatibility issues.*
4139
4140 For the most part, newer versions of Ada are upwards compatible
4141 with older versions. For example, Ada 2005 programs will almost
4142 always work when compiled as Ada 2012.
4143 However there are some exceptions (for example the fact that
4144 ``some`` is now a reserved word in Ada 2012). This
4145 switch activates several warnings to help in identifying
4146 and correcting such incompatibilities. The default is that
4147 these warnings are generated. Note that at one point Ada 2005
4148 was called Ada 0Y, hence the choice of character.
4149
4150
4151 .. index:: -gnatwY (gcc)
4152 .. index:: Ada compatibility issues warnings
4153
4154 :switch:`-gnatwY`
4155 *Disable warnings for Ada compatibility issues.*
4156
4157 This switch suppresses the warnings intended to help in identifying
4158 incompatibilities between Ada language versions.
4159
4160
4161 .. index:: -gnatw.y (gcc)
4162 .. index:: Package spec needing body
4163
4164 :switch:`-gnatw.y`
4165 *Activate information messages for why package spec needs body.*
4166
4167 There are a number of cases in which a package spec needs a body.
4168 For example, the use of pragma Elaborate_Body, or the declaration
4169 of a procedure specification requiring a completion. This switch
4170 causes information messages to be output showing why a package
4171 specification requires a body. This can be useful in the case of
4172 a large package specification which is unexpectedly requiring a
4173 body. The default is that such information messages are not output.
4174
4175
4176 .. index:: -gnatw.Y (gcc)
4177 .. index:: No information messages for why package spec needs body
4178
4179 :switch:`-gnatw.Y`
4180 *Disable information messages for why package spec needs body.*
4181
4182 This switch suppresses the output of information messages showing why
4183 a package specification needs a body.
4184
4185
4186 .. index:: -gnatwz (gcc)
4187 .. index:: Unchecked_Conversion warnings
4188
4189 :switch:`-gnatwz`
4190 *Activate warnings on unchecked conversions.*
4191
4192 This switch activates warnings for unchecked conversions
4193 where the types are known at compile time to have different
4194 sizes. The default is that such warnings are generated. Warnings are also
4195 generated for subprogram pointers with different conventions.
4196
4197
4198 .. index:: -gnatwZ (gcc)
4199
4200 :switch:`-gnatwZ`
4201 *Suppress warnings on unchecked conversions.*
4202
4203 This switch suppresses warnings for unchecked conversions
4204 where the types are known at compile time to have different
4205 sizes or conventions.
4206
4207
4208 .. index:: -gnatw.z (gcc)
4209 .. index:: Size/Alignment warnings
4210
4211 :switch:`-gnatw.z`
4212 *Activate warnings for size not a multiple of alignment.*
4213
4214 This switch activates warnings for cases of array and record types
4215 with specified ``Size`` and ``Alignment`` attributes where the
4216 size is not a multiple of the alignment, resulting in an object
4217 size that is greater than the specified size. The default
4218 is that such warnings are generated.
4219
4220
4221 .. index:: -gnatw.Z (gcc)
4222 .. index:: Size/Alignment warnings
4223
4224 :switch:`-gnatw.Z`
4225 *Suppress warnings for size not a multiple of alignment.*
4226
4227 This switch suppresses warnings for cases of array and record types
4228 with specified ``Size`` and ``Alignment`` attributes where the
4229 size is not a multiple of the alignment, resulting in an object
4230 size that is greater than the specified size. The warning can also
4231 be suppressed by giving an explicit ``Object_Size`` value.
4232
4233
4234 .. index:: -Wunused (gcc)
4235
4236 :switch:`-Wunused`
4237 The warnings controlled by the :switch:`-gnatw` switch are generated by
4238 the front end of the compiler. The GCC back end can provide
4239 additional warnings and they are controlled by the :switch:`-W` switch.
4240 For example, :switch:`-Wunused` activates back end
4241 warnings for entities that are declared but not referenced.
4242
4243
4244 .. index:: -Wuninitialized (gcc)
4245
4246 :switch:`-Wuninitialized`
4247 Similarly, :switch:`-Wuninitialized` activates
4248 the back end warning for uninitialized variables. This switch must be
4249 used in conjunction with an optimization level greater than zero.
4250
4251
4252 .. index:: -Wstack-usage (gcc)
4253
4254 :switch:`-Wstack-usage={len}`
4255 Warn if the stack usage of a subprogram might be larger than ``len`` bytes.
4256 See :ref:`Static_Stack_Usage_Analysis` for details.
4257
4258
4259 .. index:: -Wall (gcc)
4260
4261 :switch:`-Wall`
4262 This switch enables most warnings from the GCC back end.
4263 The code generator detects a number of warning situations that are missed
4264 by the GNAT front end, and this switch can be used to activate them.
4265 The use of this switch also sets the default front-end warning mode to
4266 :switch:`-gnatwa`, that is, most front-end warnings are activated as well.
4267
4268
4269 .. index:: -w (gcc)
4270
4271 :switch:`-w`
4272 Conversely, this switch suppresses warnings from the GCC back end.
4273 The use of this switch also sets the default front-end warning mode to
4274 :switch:`-gnatws`, that is, front-end warnings are suppressed as well.
4275
4276
4277 .. index:: -Werror (gcc)
4278
4279 :switch:`-Werror`
4280 This switch causes warnings from the GCC back end to be treated as
4281 errors. The warning string still appears, but the warning messages are
4282 counted as errors, and prevent the generation of an object file.
4283 The use of this switch also sets the default front-end warning mode to
4284 :switch:`-gnatwe`, that is, front-end warning messages and style check
4285 messages are treated as errors as well.
4286
4287
4288 A string of warning parameters can be used in the same parameter. For example::
4289
4290 -gnatwaGe
4291
4292
4293 will turn on all optional warnings except for unrecognized pragma warnings,
4294 and also specify that warnings should be treated as errors.
4295
4296 When no switch :switch:`-gnatw` is used, this is equivalent to:
4297
4298 * :switch:`-gnatw.a`
4299
4300 * :switch:`-gnatwB`
4301
4302 * :switch:`-gnatw.b`
4303
4304 * :switch:`-gnatwC`
4305
4306 * :switch:`-gnatw.C`
4307
4308 * :switch:`-gnatwD`
4309
4310 * :switch:`-gnatw.D`
4311
4312 * :switch:`-gnatwF`
4313
4314 * :switch:`-gnatw.F`
4315
4316 * :switch:`-gnatwg`
4317
4318 * :switch:`-gnatwH`
4319
4320 * :switch:`-gnatw.H`
4321
4322 * :switch:`-gnatwi`
4323
4324 * :switch:`-gnatwJ`
4325
4326 * :switch:`-gnatw.J`
4327
4328 * :switch:`-gnatwK`
4329
4330 * :switch:`-gnatw.K`
4331
4332 * :switch:`-gnatwL`
4333
4334 * :switch:`-gnatw.L`
4335
4336 * :switch:`-gnatwM`
4337
4338 * :switch:`-gnatw.m`
4339
4340 * :switch:`-gnatwn`
4341
4342 * :switch:`-gnatw.N`
4343
4344 * :switch:`-gnatwo`
4345
4346 * :switch:`-gnatw.O`
4347
4348 * :switch:`-gnatwP`
4349
4350 * :switch:`-gnatw.P`
4351
4352 * :switch:`-gnatwq`
4353
4354 * :switch:`-gnatw.Q`
4355
4356 * :switch:`-gnatwR`
4357
4358 * :switch:`-gnatw.R`
4359
4360 * :switch:`-gnatw.S`
4361
4362 * :switch:`-gnatwT`
4363
4364 * :switch:`-gnatw.t`
4365
4366 * :switch:`-gnatwU`
4367
4368 * :switch:`-gnatw.U`
4369
4370 * :switch:`-gnatwv`
4371
4372 * :switch:`-gnatw.v`
4373
4374 * :switch:`-gnatww`
4375
4376 * :switch:`-gnatw.W`
4377
4378 * :switch:`-gnatwx`
4379
4380 * :switch:`-gnatw.X`
4381
4382 * :switch:`-gnatwy`
4383
4384 * :switch:`-gnatw.Y`
4385
4386 * :switch:`-gnatwz`
4387
4388 * :switch:`-gnatw.z`
4389
4390 .. _Debugging_and_Assertion_Control:
4391
4392
4393
4394 Info message Control
4395 --------------------
4396
4397 In addition to the warning messages, the compiler can also generate info
4398 messages. In order to control the generation of these messages, the following
4399 switch is provided:
4400
4401 :switch:`-gnatis`
4402 *Suppress all info messages.*
4403
4404 This switch completely suppresses the output of all info messages from the
4405 GNAT front end.
4406
4407
4408
4409 Debugging and Assertion Control
4410 -------------------------------
4411
4412
4413
4414 .. index:: -gnata (gcc)
4415
4416 :switch:`-gnata`
4417 .. index:: Assert
4418 .. index:: Debug
4419 .. index:: Assertions
4420 .. index:: Precondition
4421 .. index:: Postcondition
4422 .. index:: Type invariants
4423 .. index:: Subtype predicates
4424
4425 The :switch:`-gnata` option is equivalent to the following ``Assertion_Policy`` pragma::
4426
4427 pragma Assertion_Policy (Check);
4428
4429 Which is a shorthand for::
4430
4431 pragma Assertion_Policy
4432 -- Ada RM assertion pragmas
4433 (Assert => Check,
4434 Static_Predicate => Check,
4435 Dynamic_Predicate => Check,
4436 Pre => Check,
4437 Pre'Class => Check,
4438 Post => Check,
4439 Post'Class => Check,
4440 Type_Invariant => Check,
4441 Type_Invariant'Class => Check,
4442 Default_Initial_Condition => Check,
4443 -- GNAT specific assertion pragmas
4444 Assert_And_Cut => Check,
4445 Assume => Check,
4446 Contract_Cases => Check,
4447 Debug => Check,
4448 Ghost => Check,
4449 Initial_Condition => Check,
4450 Loop_Invariant => Check,
4451 Loop_Variant => Check,
4452 Postcondition => Check,
4453 Precondition => Check,
4454 Predicate => Check,
4455 Refined_Post => Check,
4456 Subprogram_Variant => Check);
4457
4458 The pragmas ``Assert`` and ``Debug`` normally have no effect and
4459 are ignored. This switch, where ``a`` stands for 'assert', causes
4460 pragmas ``Assert`` and ``Debug`` to be activated. This switch also
4461 causes preconditions, postconditions, subtype predicates, and
4462 type invariants to be activated.
4463
4464 The pragmas have the form::
4465
4466 pragma Assert (<Boolean-expression> [, <static-string-expression>])
4467 pragma Debug (<procedure call>)
4468 pragma Type_Invariant (<type-local-name>, <Boolean-expression>)
4469 pragma Predicate (<type-local-name>, <Boolean-expression>)
4470 pragma Precondition (<Boolean-expression>, <string-expression>)
4471 pragma Postcondition (<Boolean-expression>, <string-expression>)
4472
4473 The aspects have the form::
4474
4475 with [Pre|Post|Type_Invariant|Dynamic_Predicate|Static_Predicate]
4476 => <Boolean-expression>;
4477
4478 The ``Assert`` pragma causes ``Boolean-expression`` to be tested.
4479 If the result is ``True``, the pragma has no effect (other than
4480 possible side effects from evaluating the expression). If the result is
4481 ``False``, the exception ``Assert_Failure`` declared in the package
4482 ``System.Assertions`` is raised (passing ``static-string-expression``, if
4483 present, as the message associated with the exception). If no string
4484 expression is given, the default is a string containing the file name and
4485 line number of the pragma.
4486
4487 The ``Debug`` pragma causes ``procedure`` to be called. Note that
4488 ``pragma Debug`` may appear within a declaration sequence, allowing
4489 debugging procedures to be called between declarations.
4490
4491 For the aspect specification, the ``Boolean-expression`` is evaluated.
4492 If the result is ``True``, the aspect has no effect. If the result
4493 is ``False``, the exception ``Assert_Failure`` is raised.
4494
4495 .. _Validity_Checking:
4496
4497 Validity Checking
4498 -----------------
4499
4500 .. index:: Validity Checking
4501
4502 The Ada Reference Manual defines the concept of invalid values (see
4503 RM 13.9.1). The primary source of invalid values is uninitialized
4504 variables. A scalar variable that is left uninitialized may contain
4505 an invalid value; the concept of invalid does not apply to access or
4506 composite types.
4507
4508 It is an error to read an invalid value, but the RM does not require
4509 run-time checks to detect such errors, except for some minimal
4510 checking to prevent erroneous execution (i.e. unpredictable
4511 behavior). This corresponds to the :switch:`-gnatVd` switch below,
4512 which is the default. For example, by default, if the expression of a
4513 case statement is invalid, it will raise Constraint_Error rather than
4514 causing a wild jump, and if an array index on the left-hand side of an
4515 assignment is invalid, it will raise Constraint_Error rather than
4516 overwriting an arbitrary memory location.
4517
4518 The :switch:`-gnatVa` may be used to enable additional validity checks,
4519 which are not required by the RM. These checks are often very
4520 expensive (which is why the RM does not require them). These checks
4521 are useful in tracking down uninitialized variables, but they are
4522 not usually recommended for production builds, and in particular
4523 we do not recommend using these extra validity checking options in
4524 combination with optimization, since this can confuse the optimizer.
4525 If performance is a consideration, leading to the need to optimize,
4526 then the validity checking options should not be used.
4527
4528 The other :switch:`-gnatV{x}` switches below allow finer-grained
4529 control; you can enable whichever validity checks you desire. However,
4530 for most debugging purposes, :switch:`-gnatVa` is sufficient, and the
4531 default :switch:`-gnatVd` (i.e. standard Ada behavior) is usually
4532 sufficient for non-debugging use.
4533
4534 The :switch:`-gnatB` switch tells the compiler to assume that all
4535 values are valid (that is, within their declared subtype range)
4536 except in the context of a use of the Valid attribute. This means
4537 the compiler can generate more efficient code, since the range
4538 of values is better known at compile time. However, an uninitialized
4539 variable can cause wild jumps and memory corruption in this mode.
4540
4541 The :switch:`-gnatV{x}` switch allows control over the validity
4542 checking mode as described below.
4543 The ``x`` argument is a string of letters that
4544 indicate validity checks that are performed or not performed in addition
4545 to the default checks required by Ada as described above.
4546
4547
4548 .. index:: -gnatVa (gcc)
4549
4550 :switch:`-gnatVa`
4551 *All validity checks.*
4552
4553 All validity checks are turned on.
4554 That is, :switch:`-gnatVa` is
4555 equivalent to ``gnatVcdefimoprst``.
4556
4557
4558 .. index:: -gnatVc (gcc)
4559
4560 :switch:`-gnatVc`
4561 *Validity checks for copies.*
4562
4563 The right-hand side of assignments, and the (explicit) initializing values
4564 of object declarations are validity checked.
4565
4566
4567 .. index:: -gnatVd (gcc)
4568
4569 :switch:`-gnatVd`
4570 *Default (RM) validity checks.*
4571
4572 Some validity checks are required by Ada (see RM 13.9.1 (9-11)); these
4573 (and only these) validity checks are enabled by default.
4574 For case statements (and case expressions) that lack a "when others =>"
4575 choice, a check is made that the value of the selector expression
4576 belongs to its nominal subtype. If it does not, Constraint_Error is raised.
4577 For assignments to array components (and for indexed components in some
4578 other contexts), a check is made that each index expression belongs to the
4579 corresponding index subtype. If it does not, Constraint_Error is raised.
4580 Both these validity checks may be turned off using switch :switch:`-gnatVD`.
4581 They are turned on by default. If :switch:`-gnatVD` is specified, a subsequent
4582 switch :switch:`-gnatVd` will leave the checks turned on.
4583 Switch :switch:`-gnatVD` should be used only if you are sure that all such
4584 expressions have valid values. If you use this switch and invalid values
4585 are present, then the program is erroneous, and wild jumps or memory
4586 overwriting may occur.
4587
4588
4589 .. index:: -gnatVe (gcc)
4590
4591 :switch:`-gnatVe`
4592 *Validity checks for scalar components.*
4593
4594 In the absence of this switch, assignments to scalar components of
4595 enclosing record or array objects are not validity checked, even if
4596 validity checks for assignments generally (:switch:`-gnatVc`) are turned on.
4597 Specifying this switch enables such checks.
4598 This switch has no effect if the :switch:`-gnatVc` switch is not specified.
4599
4600 .. index:: -gnatVf (gcc)
4601
4602 :switch:`-gnatVf`
4603 *Validity checks for floating-point values.*
4604
4605 Specifying this switch enables validity checking for floating-point
4606 values in the same contexts where validity checking is enabled for
4607 other scalar values.
4608 In the absence of this switch, validity checking is not performed for
4609 floating-point values. This takes precedence over other statements about
4610 performing validity checking for scalar objects in various scenarios.
4611 One way to look at it is that if this switch is not set, then whenever
4612 any of the other rules in this section use the word "scalar" they
4613 really mean "scalar and not floating-point".
4614 If :switch:`-gnatVf` is specified, then validity checking also applies
4615 for floating-point values, and NaNs and infinities are considered invalid,
4616 as well as out-of-range values for constrained types. The exact contexts
4617 in which floating-point values are checked depends on the setting of other
4618 options. For example, :switch:`-gnatVif` or :switch:`-gnatVfi`
4619 (the order does not matter) specifies that floating-point parameters of mode
4620 ``in`` should be validity checked.
4621
4622
4623 .. index:: -gnatVi (gcc)
4624
4625 :switch:`-gnatVi`
4626 *Validity checks for ``in`` mode parameters.*
4627
4628 Arguments for parameters of mode ``in`` are validity checked in function
4629 and procedure calls at the point of call.
4630
4631
4632 .. index:: -gnatVm (gcc)
4633
4634 :switch:`-gnatVm`
4635 *Validity checks for ``in out`` mode parameters.*
4636
4637 Arguments for parameters of mode ``in out`` are validity checked in
4638 procedure calls at the point of call. The ``'m'`` here stands for
4639 modify, since this concerns parameters that can be modified by the call.
4640 Note that there is no specific option to test ``out`` parameters,
4641 but any reference within the subprogram will be tested in the usual
4642 manner, and if an invalid value is copied back, any reference to it
4643 will be subject to validity checking.
4644
4645
4646 .. index:: -gnatVn (gcc)
4647
4648 :switch:`-gnatVn`
4649 *No validity checks.*
4650
4651 This switch turns off all validity checking, including the default checking
4652 for case statements and left hand side subscripts. Note that the use of
4653 the switch :switch:`-gnatp` suppresses all run-time checks, including
4654 validity checks, and thus implies :switch:`-gnatVn`. When this switch
4655 is used, it cancels any other :switch:`-gnatV` previously issued.
4656
4657
4658 .. index:: -gnatVo (gcc)
4659
4660 :switch:`-gnatVo`
4661 *Validity checks for operator and attribute operands.*
4662
4663 Scalar arguments for predefined operators and for attributes are
4664 validity checked.
4665 This includes all operators in package ``Standard``,
4666 the shift operators defined as intrinsic in package ``Interfaces``
4667 and operands for attributes such as ``Pos``. Checks are also made
4668 on individual component values for composite comparisons, and on the
4669 expressions in type conversions and qualified expressions. Checks are
4670 also made on explicit ranges using :samp:`..` (e.g., slices, loops etc).
4671
4672
4673 .. index:: -gnatVp (gcc)
4674
4675 :switch:`-gnatVp`
4676 *Validity checks for parameters.*
4677
4678 This controls the treatment of formal parameters within a subprogram (as
4679 opposed to :switch:`-gnatVi` and :switch:`-gnatVm`, which control validity
4680 testing of actual parameters of a call). If either of these call options is
4681 specified, then normally an assumption is made within a subprogram that
4682 the validity of any incoming formal parameters of the corresponding mode(s)
4683 has already been checked at the point of call and does not need rechecking.
4684 If :switch:`-gnatVp` is set, then this assumption is not made and so their
4685 validity may be checked (or rechecked) within the subprogram. If neither of
4686 the two call-related options is specified, then this switch has no effect.
4687
4688 .. index:: -gnatVr (gcc)
4689
4690 :switch:`-gnatVr`
4691 *Validity checks for function returns.*
4692
4693 The expression in simple ``return`` statements in functions is validity
4694 checked.
4695
4696
4697 .. index:: -gnatVs (gcc)
4698
4699 :switch:`-gnatVs`
4700 *Validity checks for subscripts.*
4701
4702 All subscript expressions are checked for validity, whatever context
4703 they occur in (in default mode some subscripts are not validity checked;
4704 for example, validity checking may be omitted in some cases involving
4705 a read of a component of an array).
4706
4707
4708 .. index:: -gnatVt (gcc)
4709
4710 :switch:`-gnatVt`
4711 *Validity checks for tests.*
4712
4713 Expressions used as conditions in ``if``, ``while`` or ``exit``
4714 statements are checked, as well as guard expressions in entry calls.
4715
4716
4717 The :switch:`-gnatV` switch may be followed by a string of letters
4718 to turn on a series of validity checking options.
4719 For example, :switch:`-gnatVcr`
4720 specifies that in addition to the default validity checking, copies and
4721 function return expressions are to be validity checked.
4722 In order to make it easier to specify the desired combination of effects,
4723 the upper case letters ``CDFIMORST`` may
4724 be used to turn off the corresponding lower case option.
4725 Thus :switch:`-gnatVaM` turns on all validity checking options except for
4726 checking of ``in out`` parameters.
4727
4728 The specification of additional validity checking generates extra code (and
4729 in the case of :switch:`-gnatVa` the code expansion can be substantial).
4730 However, these additional checks can be very useful in detecting
4731 uninitialized variables, incorrect use of unchecked conversion, and other
4732 errors leading to invalid values. The use of pragma ``Initialize_Scalars``
4733 is useful in conjunction with the extra validity checking, since this
4734 ensures that wherever possible uninitialized variables have invalid values.
4735
4736 See also the pragma ``Validity_Checks`` which allows modification of
4737 the validity checking mode at the program source level, and also allows for
4738 temporary disabling of validity checks.
4739
4740 .. _Style_Checking:
4741
4742 Style Checking
4743 --------------
4744
4745 .. index:: Style checking
4746
4747 .. index:: -gnaty (gcc)
4748
4749 The :switch:`-gnaty` switch causes the compiler to
4750 enforce specified style rules. A limited set of style rules has been used
4751 in writing the GNAT sources themselves. This switch allows user programs
4752 to activate all or some of these checks. If the source program fails a
4753 specified style check, an appropriate message is given, preceded by
4754 the character sequence '(style)'. This message does not prevent
4755 successful compilation (unless the :switch:`-gnatwe` switch is used).
4756
4757 Note that this is by no means intended to be a general facility for
4758 checking arbitrary coding standards. It is simply an embedding of the
4759 style rules we have chosen for the GNAT sources. If you are starting
4760 a project which does not have established style standards, you may
4761 find it useful to adopt the entire set of GNAT coding standards, or
4762 some subset of them.
4763
4764 .. only:: PRO or GPL
4765
4766 If you already have an established set of coding
4767 standards, then the selected style checking options may
4768 indeed correspond to choices you have made, but for general checking
4769 of an existing set of coding rules, you should look to the gnatcheck
4770 tool, which is designed for that purpose.
4771
4772 The string ``x`` is a sequence of letters or digits
4773 indicating the particular style
4774 checks to be performed. The following checks are defined:
4775
4776
4777 .. index:: -gnaty[0-9] (gcc)
4778
4779 :switch:`-gnaty0`
4780 *Specify indentation level.*
4781
4782 If a digit from 1-9 appears
4783 in the string after :switch:`-gnaty`
4784 then proper indentation is checked, with the digit indicating the
4785 indentation level required. A value of zero turns off this style check.
4786 The rule checks that the following constructs start on a column that is
4787 one plus a multiple of the alignment level:
4788
4789 * beginnings of declarations (except record component declarations)
4790 and statements;
4791
4792 * beginnings of the structural components of compound statements;
4793
4794 * ``end`` keyword that completes the declaration of a program unit declaration
4795 or body or that completes a compound statement.
4796
4797 Full line comments must be
4798 aligned with the ``--`` starting on a column that is one plus a multiple of
4799 the alignment level, or they may be aligned the same way as the following
4800 non-blank line (this is useful when full line comments appear in the middle
4801 of a statement), or they may be aligned with the source line on the previous
4802 non-blank line.
4803
4804 .. index:: -gnatya (gcc)
4805
4806 :switch:`-gnatya`
4807 *Check attribute casing.*
4808
4809 Attribute names, including the case of keywords such as ``digits``
4810 used as attributes names, must be written in mixed case, that is, the
4811 initial letter and any letter following an underscore must be uppercase.
4812 All other letters must be lowercase.
4813
4814
4815 .. index:: -gnatyA (gcc)
4816
4817 :switch:`-gnatyA`
4818 *Use of array index numbers in array attributes.*
4819
4820 When using the array attributes First, Last, Range,
4821 or Length, the index number must be omitted for one-dimensional arrays
4822 and is required for multi-dimensional arrays.
4823
4824
4825 .. index:: -gnatyb (gcc)
4826
4827 :switch:`-gnatyb`
4828 *Blanks not allowed at statement end.*
4829
4830 Trailing blanks are not allowed at the end of statements. The purpose of this
4831 rule, together with h (no horizontal tabs), is to enforce a canonical format
4832 for the use of blanks to separate source tokens.
4833
4834
4835 .. index:: -gnatyB (gcc)
4836
4837 :switch:`-gnatyB`
4838 *Check Boolean operators.*
4839
4840 The use of AND/OR operators is not permitted except in the cases of modular
4841 operands, array operands, and simple stand-alone boolean variables or
4842 boolean constants. In all other cases ``and then``/`or else` are
4843 required.
4844
4845
4846 .. index:: -gnatyc (gcc)
4847
4848 :switch:`-gnatyc`
4849 *Check comments, double space.*
4850
4851 Comments must meet the following set of rules:
4852
4853 * The ``--`` that starts the column must either start in column one,
4854 or else at least one blank must precede this sequence.
4855
4856 * Comments that follow other tokens on a line must have at least one blank
4857 following the ``--`` at the start of the comment.
4858
4859 * Full line comments must have at least two blanks following the
4860 ``--`` that starts the comment, with the following exceptions.
4861
4862 * A line consisting only of the ``--`` characters, possibly preceded
4863 by blanks is permitted.
4864
4865 * A comment starting with ``--x`` where ``x`` is a special character
4866 is permitted.
4867 This allows proper processing of the output from specialized tools
4868 such as ``gnatprep`` (where ``--!`` is used) and in earlier versions of the SPARK
4869 annotation
4870 language (where ``--#`` is used). For the purposes of this rule, a
4871 special character is defined as being in one of the ASCII ranges
4872 ``16#21#...16#2F#`` or ``16#3A#...16#3F#``.
4873 Note that this usage is not permitted
4874 in GNAT implementation units (i.e., when :switch:`-gnatg` is used).
4875
4876 * A line consisting entirely of minus signs, possibly preceded by blanks, is
4877 permitted. This allows the construction of box comments where lines of minus
4878 signs are used to form the top and bottom of the box.
4879
4880 * A comment that starts and ends with ``--`` is permitted as long as at
4881 least one blank follows the initial ``--``. Together with the preceding
4882 rule, this allows the construction of box comments, as shown in the following
4883 example:
4884
4885 .. code-block:: ada
4886
4887 ---------------------------
4888 -- This is a box comment --
4889 -- with two text lines. --
4890 ---------------------------
4891
4892
4893 .. index:: -gnatyC (gcc)
4894
4895 :switch:`-gnatyC`
4896 *Check comments, single space.*
4897
4898 This is identical to ``c`` except that only one space
4899 is required following the ``--`` of a comment instead of two.
4900
4901
4902 .. index:: -gnatyd (gcc)
4903
4904 :switch:`-gnatyd`
4905 *Check no DOS line terminators present.*
4906
4907 All lines must be terminated by a single ASCII.LF
4908 character (in particular the DOS line terminator sequence CR/LF is not
4909 allowed).
4910
4911
4912 .. index:: -gnatyD (gcc)
4913
4914 :switch:`-gnatyD`
4915 *Check declared identifiers in mixed case.*
4916
4917 Declared identifiers must be in mixed case, as in
4918 This_Is_An_Identifier. Use -gnatyr in addition to ensure
4919 that references match declarations.
4920
4921
4922 .. index:: -gnatye (gcc)
4923
4924 :switch:`-gnatye`
4925 *Check end/exit labels.*
4926
4927 Optional labels on ``end`` statements ending subprograms and on
4928 ``exit`` statements exiting named loops, are required to be present.
4929
4930
4931 .. index:: -gnatyf (gcc)
4932
4933 :switch:`-gnatyf`
4934 *No form feeds or vertical tabs.*
4935
4936 Neither form feeds nor vertical tab characters are permitted
4937 in the source text.
4938
4939
4940 .. index:: -gnatyg (gcc)
4941
4942 :switch:`-gnatyg`
4943 *GNAT style mode.*
4944
4945 The set of style check switches is set to match that used by the GNAT sources.
4946 This may be useful when developing code that is eventually intended to be
4947 incorporated into GNAT. Currently this is equivalent to
4948 :switch:`-gnatyydISuxz`) but additional style switches may be added to this
4949 set in the future without advance notice.
4950
4951
4952 .. index:: -gnatyh (gcc)
4953
4954 :switch:`-gnatyh`
4955 *No horizontal tabs.*
4956
4957 Horizontal tab characters are not permitted in the source text.
4958 Together with the b (no blanks at end of line) check, this
4959 enforces a canonical form for the use of blanks to separate
4960 source tokens.
4961
4962
4963 .. index:: -gnatyi (gcc)
4964
4965 :switch:`-gnatyi`
4966 *Check if-then layout.*
4967
4968 The keyword ``then`` must appear either on the same
4969 line as corresponding ``if``, or on a line on its own, lined
4970 up under the ``if``.
4971
4972
4973 .. index:: -gnatyI (gcc)
4974
4975 :switch:`-gnatyI`
4976 *check mode IN keywords.*
4977
4978 Mode ``in`` (the default mode) is not
4979 allowed to be given explicitly. ``in out`` is fine,
4980 but not ``in`` on its own.
4981
4982
4983 .. index:: -gnatyk (gcc)
4984
4985 :switch:`-gnatyk`
4986 *Check keyword casing.*
4987
4988 All keywords must be in lower case (with the exception of keywords
4989 such as ``digits`` used as attribute names to which this check
4990 does not apply). A single error is reported for each line breaking
4991 this rule even if multiple casing issues exist on a same line.
4992
4993
4994 .. index:: -gnatyl (gcc)
4995
4996 :switch:`-gnatyl`
4997 *Check layout.*
4998
4999 Layout of statement and declaration constructs must follow the
5000 recommendations in the Ada Reference Manual, as indicated by the
5001 form of the syntax rules. For example an ``else`` keyword must
5002 be lined up with the corresponding ``if`` keyword.
5003
5004 There are two respects in which the style rule enforced by this check
5005 option are more liberal than those in the Ada Reference Manual. First
5006 in the case of record declarations, it is permissible to put the
5007 ``record`` keyword on the same line as the ``type`` keyword, and
5008 then the ``end`` in ``end record`` must line up under ``type``.
5009 This is also permitted when the type declaration is split on two lines.
5010 For example, any of the following three layouts is acceptable:
5011
5012 .. code-block:: ada
5013
5014 type q is record
5015 a : integer;
5016 b : integer;
5017 end record;
5018
5019 type q is
5020 record
5021 a : integer;
5022 b : integer;
5023 end record;
5024
5025 type q is
5026 record
5027 a : integer;
5028 b : integer;
5029 end record;
5030
5031 Second, in the case of a block statement, a permitted alternative
5032 is to put the block label on the same line as the ``declare`` or
5033 ``begin`` keyword, and then line the ``end`` keyword up under
5034 the block label. For example both the following are permitted:
5035
5036 .. code-block:: ada
5037
5038 Block : declare
5039 A : Integer := 3;
5040 begin
5041 Proc (A, A);
5042 end Block;
5043
5044 Block :
5045 declare
5046 A : Integer := 3;
5047 begin
5048 Proc (A, A);
5049 end Block;
5050
5051 The same alternative format is allowed for loops. For example, both of
5052 the following are permitted:
5053
5054 .. code-block:: ada
5055
5056 Clear : while J < 10 loop
5057 A (J) := 0;
5058 end loop Clear;
5059
5060 Clear :
5061 while J < 10 loop
5062 A (J) := 0;
5063 end loop Clear;
5064
5065
5066 .. index:: -gnatyLnnn (gcc)
5067
5068 :switch:`-gnatyL`
5069 *Set maximum nesting level.*
5070
5071 The maximum level of nesting of constructs (including subprograms, loops,
5072 blocks, packages, and conditionals) may not exceed the given value
5073 *nnn*. A value of zero disconnects this style check.
5074
5075
5076 .. index:: -gnatym (gcc)
5077
5078 :switch:`-gnatym`
5079 *Check maximum line length.*
5080
5081 The length of source lines must not exceed 79 characters, including
5082 any trailing blanks. The value of 79 allows convenient display on an
5083 80 character wide device or window, allowing for possible special
5084 treatment of 80 character lines. Note that this count is of
5085 characters in the source text. This means that a tab character counts
5086 as one character in this count and a wide character sequence counts as
5087 a single character (however many bytes are needed in the encoding).
5088
5089
5090 .. index:: -gnatyMnnn (gcc)
5091
5092 :switch:`-gnatyM`
5093 *Set maximum line length.*
5094
5095 The length of lines must not exceed the
5096 given value *nnn*. The maximum value that can be specified is 32767.
5097 If neither style option for setting the line length is used, then the
5098 default is 255. This also controls the maximum length of lexical elements,
5099 where the only restriction is that they must fit on a single line.
5100
5101
5102 .. index:: -gnatyn (gcc)
5103
5104 :switch:`-gnatyn`
5105 *Check casing of entities in Standard.*
5106
5107 Any identifier from Standard must be cased
5108 to match the presentation in the Ada Reference Manual (for example,
5109 ``Integer`` and ``ASCII.NUL``).
5110
5111
5112 .. index:: -gnatyN (gcc)
5113
5114 :switch:`-gnatyN`
5115 *Turn off all style checks.*
5116
5117 All style check options are turned off.
5118
5119
5120 .. index:: -gnatyo (gcc)
5121
5122 :switch:`-gnatyo`
5123 *Check order of subprogram bodies.*
5124
5125 All subprogram bodies in a given scope
5126 (e.g., a package body) must be in alphabetical order. The ordering
5127 rule uses normal Ada rules for comparing strings, ignoring casing
5128 of letters, except that if there is a trailing numeric suffix, then
5129 the value of this suffix is used in the ordering (e.g., Junk2 comes
5130 before Junk10).
5131
5132
5133 .. index:: -gnatyO (gcc)
5134
5135 :switch:`-gnatyO`
5136 *Check that overriding subprograms are explicitly marked as such.*
5137
5138 This applies to all subprograms of a derived type that override a primitive
5139 operation of the type, for both tagged and untagged types. In particular,
5140 the declaration of a primitive operation of a type extension that overrides
5141 an inherited operation must carry an overriding indicator. Another case is
5142 the declaration of a function that overrides a predefined operator (such
5143 as an equality operator).
5144
5145
5146 .. index:: -gnatyp (gcc)
5147
5148 :switch:`-gnatyp`
5149 *Check pragma casing.*
5150
5151 Pragma names must be written in mixed case, that is, the
5152 initial letter and any letter following an underscore must be uppercase.
5153 All other letters must be lowercase. An exception is that SPARK_Mode is
5154 allowed as an alternative for Spark_Mode.
5155
5156
5157 .. index:: -gnatyr (gcc)
5158
5159 :switch:`-gnatyr`
5160 *Check references.*
5161
5162 All identifier references must be cased in the same way as the
5163 corresponding declaration. No specific casing style is imposed on
5164 identifiers. The only requirement is for consistency of references
5165 with declarations.
5166
5167
5168 .. index:: -gnatys (gcc)
5169
5170 :switch:`-gnatys`
5171 *Check separate specs.*
5172
5173 Separate declarations ('specs') are required for subprograms (a
5174 body is not allowed to serve as its own declaration). The only
5175 exception is that parameterless library level procedures are
5176 not required to have a separate declaration. This exception covers
5177 the most frequent form of main program procedures.
5178
5179
5180 .. index:: -gnatyS (gcc)
5181
5182 :switch:`-gnatyS`
5183 *Check no statements after then/else.*
5184
5185 No statements are allowed
5186 on the same line as a ``then`` or ``else`` keyword following the
5187 keyword in an ``if`` statement. ``or else`` and ``and then`` are not
5188 affected, and a special exception allows a pragma to appear after ``else``.
5189
5190
5191 .. index:: -gnatyt (gcc)
5192
5193 :switch:`-gnatyt`
5194 *Check token spacing.*
5195
5196 The following token spacing rules are enforced:
5197
5198 * The keywords ``abs`` and ``not`` must be followed by a space.
5199
5200 * The token ``=>`` must be surrounded by spaces.
5201
5202 * The token ``<>`` must be preceded by a space or a left parenthesis.
5203
5204 * Binary operators other than ``**`` must be surrounded by spaces.
5205 There is no restriction on the layout of the ``**`` binary operator.
5206
5207 * Colon must be surrounded by spaces.
5208
5209 * Colon-equal (assignment, initialization) must be surrounded by spaces.
5210
5211 * Comma must be the first non-blank character on the line, or be
5212 immediately preceded by a non-blank character, and must be followed
5213 by a space.
5214
5215 * If the token preceding a left parenthesis ends with a letter or digit, then
5216 a space must separate the two tokens.
5217
5218 * If the token following a right parenthesis starts with a letter or digit, then
5219 a space must separate the two tokens.
5220
5221 * A right parenthesis must either be the first non-blank character on
5222 a line, or it must be preceded by a non-blank character.
5223
5224 * A semicolon must not be preceded by a space, and must not be followed by
5225 a non-blank character.
5226
5227 * A unary plus or minus may not be followed by a space.
5228
5229 * A vertical bar must be surrounded by spaces.
5230
5231 Exactly one blank (and no other white space) must appear between
5232 a ``not`` token and a following ``in`` token.
5233
5234
5235 .. index:: -gnatyu (gcc)
5236
5237 :switch:`-gnatyu`
5238 *Check unnecessary blank lines.*
5239
5240 Unnecessary blank lines are not allowed. A blank line is considered
5241 unnecessary if it appears at the end of the file, or if more than
5242 one blank line occurs in sequence.
5243
5244
5245 .. index:: -gnatyx (gcc)
5246
5247 :switch:`-gnatyx`
5248 *Check extra parentheses.*
5249
5250 Unnecessary extra levels of parentheses (C-style) are not allowed
5251 around conditions (or selection expressions) in ``if``, ``while``,
5252 ``case``, and ``exit`` statements, as well as part of ranges.
5253
5254
5255 .. index:: -gnatyy (gcc)
5256
5257 :switch:`-gnatyy`
5258 *Set all standard style check options.*
5259
5260 This is equivalent to ``gnaty3aAbcefhiklmnprst``, that is all checking
5261 options enabled with the exception of :switch:`-gnatyB`, :switch:`-gnatyd`,
5262 :switch:`-gnatyI`, :switch:`-gnatyLnnn`, :switch:`-gnatyo`, :switch:`-gnatyO`,
5263 :switch:`-gnatyS`, :switch:`-gnatyu`, and :switch:`-gnatyx`.
5264
5265
5266 .. index:: -gnatyz (gcc)
5267
5268 :switch:`-gnatyz`
5269 *Check extra parentheses (operator precedence).*
5270
5271 Extra levels of parentheses that are not required by operator precedence
5272 rules are flagged. See also ``-gnatyx``.
5273
5274
5275 .. index:: -gnaty- (gcc)
5276
5277 :switch:`-gnaty-`
5278 *Remove style check options.*
5279
5280 This causes any subsequent options in the string to act as canceling the
5281 corresponding style check option. To cancel maximum nesting level control,
5282 use the ``L`` parameter without any integer value after that, because any
5283 digit following *-* in the parameter string of the :switch:`-gnaty`
5284 option will be treated as canceling the indentation check. The same is true
5285 for the ``M`` parameter. ``y`` and ``N`` parameters are not
5286 allowed after *-*.
5287
5288
5289 .. index:: -gnaty+ (gcc)
5290
5291 :switch:`-gnaty+`
5292 *Enable style check options.*
5293
5294 This causes any subsequent options in the string to enable the corresponding
5295 style check option. That is, it cancels the effect of a previous -,
5296 if any.
5297
5298
5299 .. end of switch description (leave this comment to ease automatic parsing for
5300 .. GNAT Studio)
5301
5302 In the above rules, appearing in column one is always permitted, that is,
5303 counts as meeting either a requirement for a required preceding space,
5304 or as meeting a requirement for no preceding space.
5305
5306 Appearing at the end of a line is also always permitted, that is, counts
5307 as meeting either a requirement for a following space, or as meeting
5308 a requirement for no following space.
5309
5310 If any of these style rules is violated, a message is generated giving
5311 details on the violation. The initial characters of such messages are
5312 always '`(style)`'. Note that these messages are treated as warning
5313 messages, so they normally do not prevent the generation of an object
5314 file. The :switch:`-gnatwe` switch can be used to treat warning messages,
5315 including style messages, as fatal errors.
5316
5317 The switch :switch:`-gnaty` on its own (that is not
5318 followed by any letters or digits) is equivalent
5319 to the use of :switch:`-gnatyy` as described above, that is all
5320 built-in standard style check options are enabled.
5321
5322 The switch :switch:`-gnatyN` clears any previously set style checks.
5323
5324 .. _Run-Time_Checks:
5325
5326 Run-Time Checks
5327 ---------------
5328
5329 .. index:: Division by zero
5330
5331 .. index:: Access before elaboration
5332
5333 .. index:: Checks, division by zero
5334
5335 .. index:: Checks, access before elaboration
5336
5337 .. index:: Checks, stack overflow checking
5338
5339 By default, the following checks are suppressed: stack overflow
5340 checks, and checks for access before elaboration on subprogram
5341 calls. All other checks, including overflow checks, range checks and
5342 array bounds checks, are turned on by default. The following ``gcc``
5343 switches refine this default behavior.
5344
5345 .. index:: -gnatp (gcc)
5346
5347 :switch:`-gnatp`
5348 .. index:: Suppressing checks
5349
5350 .. index:: Checks, suppressing
5351
5352 This switch causes the unit to be compiled
5353 as though ``pragma Suppress (All_checks)``
5354 had been present in the source. Validity checks are also eliminated (in
5355 other words :switch:`-gnatp` also implies :switch:`-gnatVn`.
5356 Use this switch to improve the performance
5357 of the code at the expense of safety in the presence of invalid data or
5358 program bugs.
5359
5360 Note that when checks are suppressed, the compiler is allowed, but not
5361 required, to omit the checking code. If the run-time cost of the
5362 checking code is zero or near-zero, the compiler will generate it even
5363 if checks are suppressed. In particular, if the compiler can prove
5364 that a certain check will necessarily fail, it will generate code to
5365 do an unconditional 'raise', even if checks are suppressed. The
5366 compiler warns in this case. Another case in which checks may not be
5367 eliminated is when they are embedded in certain run-time routines such
5368 as math library routines.
5369
5370 Of course, run-time checks are omitted whenever the compiler can prove
5371 that they will not fail, whether or not checks are suppressed.
5372
5373 Note that if you suppress a check that would have failed, program
5374 execution is erroneous, which means the behavior is totally
5375 unpredictable. The program might crash, or print wrong answers, or
5376 do anything else. It might even do exactly what you wanted it to do
5377 (and then it might start failing mysteriously next week or next
5378 year). The compiler will generate code based on the assumption that
5379 the condition being checked is true, which can result in erroneous
5380 execution if that assumption is wrong.
5381
5382 The checks subject to suppression include all the checks defined by the Ada
5383 standard, as well as all implementation-defined checks,
5384 including any checks introduced using ``pragma Check_Name``.
5385
5386 If the code depends on certain checks being active, you can use
5387 pragma ``Unsuppress`` either as a configuration pragma or as
5388 a local pragma to make sure that a specified check is performed
5389 even if ``gnatp`` is specified.
5390
5391 The :switch:`-gnatp` switch has no effect if a subsequent
5392 :switch:`-gnat-p` switch appears.
5393
5394
5395 .. index:: -gnat-p (gcc)
5396 .. index:: Suppressing checks
5397 .. index:: Checks, suppressing
5398 .. index:: Suppress
5399
5400 :switch:`-gnat-p`
5401 This switch cancels the effect of a previous ``gnatp`` switch.
5402
5403
5404 .. index:: -gnato?? (gcc)
5405 .. index:: Overflow checks
5406 .. index:: Overflow mode
5407 .. index:: Check, overflow
5408
5409 :switch:`-gnato??`
5410 This switch controls the mode used for computing intermediate
5411 arithmetic integer operations, and also enables overflow checking.
5412 For a full description of overflow mode and checking control, see
5413 the 'Overflow Check Handling in GNAT' appendix in this
5414 User's Guide.
5415
5416 Overflow checks are always enabled by this switch. The argument
5417 controls the mode, using the codes
5418
5419
5420 *1 = STRICT*
5421 In STRICT mode, intermediate operations are always done using the
5422 base type, and overflow checking ensures that the result is within
5423 the base type range.
5424
5425
5426 *2 = MINIMIZED*
5427 In MINIMIZED mode, overflows in intermediate operations are avoided
5428 where possible by using a larger integer type for the computation
5429 (typically ``Long_Long_Integer``). Overflow checking ensures that
5430 the result fits in this larger integer type.
5431
5432
5433 *3 = ELIMINATED*
5434 In ELIMINATED mode, overflows in intermediate operations are avoided
5435 by using multi-precision arithmetic. In this case, overflow checking
5436 has no effect on intermediate operations (since overflow is impossible).
5437
5438 If two digits are present after :switch:`-gnato` then the first digit
5439 sets the mode for expressions outside assertions, and the second digit
5440 sets the mode for expressions within assertions. Here assertions is used
5441 in the technical sense (which includes for example precondition and
5442 postcondition expressions).
5443
5444 If one digit is present, the corresponding mode is applicable to both
5445 expressions within and outside assertion expressions.
5446
5447 If no digits are present, the default is to enable overflow checks
5448 and set STRICT mode for both kinds of expressions. This is compatible
5449 with the use of :switch:`-gnato` in previous versions of GNAT.
5450
5451 .. index:: Machine_Overflows
5452
5453 Note that the :switch:`-gnato??` switch does not affect the code generated
5454 for any floating-point operations; it applies only to integer semantics.
5455 For floating-point, GNAT has the ``Machine_Overflows``
5456 attribute set to ``False`` and the normal mode of operation is to
5457 generate IEEE NaN and infinite values on overflow or invalid operations
5458 (such as dividing 0.0 by 0.0).
5459
5460 The reason that we distinguish overflow checking from other kinds of
5461 range constraint checking is that a failure of an overflow check, unlike
5462 for example the failure of a range check, can result in an incorrect
5463 value, but cannot cause random memory destruction (like an out of range
5464 subscript), or a wild jump (from an out of range case value). Overflow
5465 checking is also quite expensive in time and space, since in general it
5466 requires the use of double length arithmetic.
5467
5468 Note again that the default is :switch:`-gnato11` (equivalent to :switch:`-gnato1`),
5469 so overflow checking is performed in STRICT mode by default.
5470
5471
5472 .. index:: -gnatE (gcc)
5473 .. index:: Elaboration checks
5474 .. index:: Check, elaboration
5475
5476 :switch:`-gnatE`
5477 Enables dynamic checks for access-before-elaboration
5478 on subprogram calls and generic instantiations.
5479 Note that :switch:`-gnatE` is not necessary for safety, because in the
5480 default mode, GNAT ensures statically that the checks would not fail.
5481 For full details of the effect and use of this switch,
5482 :ref:`Compiling_with_gcc`.
5483
5484
5485 .. index:: -fstack-check (gcc)
5486 .. index:: Stack Overflow Checking
5487 .. index:: Checks, stack overflow checking
5488
5489 :switch:`-fstack-check`
5490 Activates stack overflow checking. For full details of the effect and use of
5491 this switch see :ref:`Stack_Overflow_Checking`.
5492
5493 .. index:: Unsuppress
5494
5495 The setting of these switches only controls the default setting of the
5496 checks. You may modify them using either ``Suppress`` (to remove
5497 checks) or ``Unsuppress`` (to add back suppressed checks) pragmas in
5498 the program source.
5499
5500
5501 .. _Using_gcc_for_Syntax_Checking:
5502
5503 Using ``gcc`` for Syntax Checking
5504 ---------------------------------
5505
5506 .. index:: -gnats (gcc)
5507
5508 :switch:`-gnats`
5509 The ``s`` stands for 'syntax'.
5510
5511 Run GNAT in syntax checking only mode. For
5512 example, the command
5513
5514 ::
5515
5516 $ gcc -c -gnats x.adb
5517
5518 compiles file :file:`x.adb` in syntax-check-only mode. You can check a
5519 series of files in a single command
5520 , and can use wildcards to specify such a group of files.
5521 Note that you must specify the :switch:`-c` (compile
5522 only) flag in addition to the :switch:`-gnats` flag.
5523
5524 You may use other switches in conjunction with :switch:`-gnats`. In
5525 particular, :switch:`-gnatl` and :switch:`-gnatv` are useful to control the
5526 format of any generated error messages.
5527
5528 When the source file is empty or contains only empty lines and/or comments,
5529 the output is a warning:
5530
5531
5532 ::
5533
5534 $ gcc -c -gnats -x ada toto.txt
5535 toto.txt:1:01: warning: empty file, contains no compilation units
5536 $
5537
5538
5539 Otherwise, the output is simply the error messages, if any. No object file or
5540 ALI file is generated by a syntax-only compilation. Also, no units other
5541 than the one specified are accessed. For example, if a unit ``X``
5542 |withs| a unit ``Y``, compiling unit ``X`` in syntax
5543 check only mode does not access the source file containing unit
5544 ``Y``.
5545
5546 .. index:: Multiple units, syntax checking
5547
5548 Normally, GNAT allows only a single unit in a source file. However, this
5549 restriction does not apply in syntax-check-only mode, and it is possible
5550 to check a file containing multiple compilation units concatenated
5551 together. This is primarily used by the ``gnatchop`` utility
5552 (:ref:`Renaming_Files_with_gnatchop`).
5553
5554 .. _Using_gcc_for_Semantic_Checking:
5555
5556 Using ``gcc`` for Semantic Checking
5557 -----------------------------------
5558
5559
5560
5561 .. index:: -gnatc (gcc)
5562
5563 :switch:`-gnatc`
5564 The ``c`` stands for 'check'.
5565 Causes the compiler to operate in semantic check mode,
5566 with full checking for all illegalities specified in the
5567 Ada Reference Manual, but without generation of any object code
5568 (no object file is generated).
5569
5570 Because dependent files must be accessed, you must follow the GNAT
5571 semantic restrictions on file structuring to operate in this mode:
5572
5573 * The needed source files must be accessible
5574 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`).
5575
5576 * Each file must contain only one compilation unit.
5577
5578 * The file name and unit name must match (:ref:`File_Naming_Rules`).
5579
5580 The output consists of error messages as appropriate. No object file is
5581 generated. An :file:`ALI` file is generated for use in the context of
5582 cross-reference tools, but this file is marked as not being suitable
5583 for binding (since no object file is generated).
5584 The checking corresponds exactly to the notion of
5585 legality in the Ada Reference Manual.
5586
5587 Any unit can be compiled in semantics-checking-only mode, including
5588 units that would not normally be compiled (subunits,
5589 and specifications where a separate body is present).
5590
5591 .. _Compiling_Different_Versions_of_Ada:
5592
5593 Compiling Different Versions of Ada
5594 -----------------------------------
5595
5596 The switches described in this section allow you to explicitly specify
5597 the version of the Ada language that your programs are written in.
5598 The default mode is Ada 2012,
5599 but you can also specify Ada 95, Ada 2005 mode, or
5600 indicate Ada 83 compatibility mode.
5601
5602
5603 .. index:: Compatibility with Ada 83
5604 .. index:: -gnat83 (gcc)
5605 .. index:: ACVC, Ada 83 tests
5606 .. index:: Ada 83 mode
5607
5608 :switch:`-gnat83` (Ada 83 Compatibility Mode)
5609 Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
5610 specifies that the program is to be compiled in Ada 83 mode. With
5611 :switch:`-gnat83`, GNAT rejects most post-Ada 83 extensions and applies Ada 83
5612 semantics where this can be done easily.
5613 It is not possible to guarantee this switch does a perfect
5614 job; some subtle tests, such as are
5615 found in earlier ACVC tests (and that have been removed from the ACATS suite
5616 for Ada 95), might not compile correctly.
5617 Nevertheless, this switch may be useful in some circumstances, for example
5618 where, due to contractual reasons, existing code needs to be maintained
5619 using only Ada 83 features.
5620
5621 With few exceptions (most notably the need to use ``<>`` on
5622 unconstrained :index:`generic formal parameters <Generic formal parameters>`,
5623 the use of the new Ada 95 / Ada 2005
5624 reserved words, and the use of packages
5625 with optional bodies), it is not necessary to specify the
5626 :switch:`-gnat83` switch when compiling Ada 83 programs, because, with rare
5627 exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
5628 a correct Ada 83 program is usually also a correct program
5629 in these later versions of the language standard. For further information
5630 please refer to the *Compatibility and Porting Guide* chapter in the
5631 :title:`GNAT Reference Manual`.
5632
5633
5634 .. index:: -gnat95 (gcc)
5635 .. index:: Ada 95 mode
5636
5637 :switch:`-gnat95` (Ada 95 mode)
5638 This switch directs the compiler to implement the Ada 95 version of the
5639 language.
5640 Since Ada 95 is almost completely upwards
5641 compatible with Ada 83, Ada 83 programs may generally be compiled using
5642 this switch (see the description of the :switch:`-gnat83` switch for further
5643 information about Ada 83 mode).
5644 If an Ada 2005 program is compiled in Ada 95 mode,
5645 uses of the new Ada 2005 features will cause error
5646 messages or warnings.
5647
5648 This switch also can be used to cancel the effect of a previous
5649 :switch:`-gnat83`, :switch:`-gnat05/2005`, or :switch:`-gnat12/2012`
5650 switch earlier in the command line.
5651
5652
5653 .. index:: -gnat05 (gcc)
5654 .. index:: -gnat2005 (gcc)
5655 .. index:: Ada 2005 mode
5656
5657 :switch:`-gnat05` or :switch:`-gnat2005` (Ada 2005 mode)
5658 This switch directs the compiler to implement the Ada 2005 version of the
5659 language, as documented in the official Ada standards document.
5660 Since Ada 2005 is almost completely upwards
5661 compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
5662 may generally be compiled using this switch (see the description of the
5663 :switch:`-gnat83` and :switch:`-gnat95` switches for further
5664 information).
5665
5666
5667 .. index:: -gnat12 (gcc)
5668 .. index:: -gnat2012 (gcc)
5669 .. index:: Ada 2012 mode
5670
5671 :switch:`-gnat12` or :switch:`-gnat2012` (Ada 2012 mode)
5672 This switch directs the compiler to implement the Ada 2012 version of the
5673 language (also the default).
5674 Since Ada 2012 is almost completely upwards
5675 compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
5676 Ada 83 and Ada 95 programs
5677 may generally be compiled using this switch (see the description of the
5678 :switch:`-gnat83`, :switch:`-gnat95`, and :switch:`-gnat05/2005` switches
5679 for further information).
5680
5681
5682 .. index:: -gnat2022 (gcc)
5683 .. index:: Ada 2022 mode
5684
5685 :switch:`-gnat2022` (Ada 2022 mode)
5686 This switch directs the compiler to implement the Ada 2022 version of the
5687 language.
5688
5689
5690 .. index:: -gnatX0 (gcc)
5691 .. index:: Ada language extensions
5692 .. index:: GNAT extensions
5693
5694 :switch:`-gnatX0` (Enable GNAT Extensions)
5695 This switch directs the compiler to implement the latest version of the
5696 language (currently Ada 2022) and also to enable certain GNAT implementation
5697 extensions that are not part of any Ada standard. For a full list of these
5698 extensions, see the GNAT reference manual, ``Pragma Extensions_Allowed``.
5699
5700 .. index:: -gnatX (gcc)
5701 .. index:: Ada language extensions
5702 .. index:: GNAT extensions
5703
5704 :switch:`-gnatX` (Enable core GNAT Extensions)
5705 This switch is similar to -gnatX0 except that only some, not all, of the
5706 GNAT-defined language extensions are enabled. For a list of the
5707 extensions enabled by this switch, see the GNAT reference manual
5708 ``Pragma Extensions_Allowed`` and the description of that pragma's
5709 "On" (as opposed to "All") argument.
5710
5711
5712 .. _Character_Set_Control:
5713
5714 Character Set Control
5715 ---------------------
5716
5717 .. index:: -gnati (gcc)
5718
5719 :switch:`-gnati{c}`
5720 Normally GNAT recognizes the Latin-1 character set in source program
5721 identifiers, as described in the Ada Reference Manual.
5722 This switch causes
5723 GNAT to recognize alternate character sets in identifiers. ``c`` is a
5724 single character indicating the character set, as follows:
5725
5726 ========== ======================================================
5727 *1* ISO 8859-1 (Latin-1) identifiers
5728 *2* ISO 8859-2 (Latin-2) letters allowed in identifiers
5729 *3* ISO 8859-3 (Latin-3) letters allowed in identifiers
5730 *4* ISO 8859-4 (Latin-4) letters allowed in identifiers
5731 *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers
5732 *9* ISO 8859-15 (Latin-9) letters allowed in identifiers
5733 *p* IBM PC letters (code page 437) allowed in identifiers
5734 *8* IBM PC letters (code page 850) allowed in identifiers
5735 *f* Full upper-half codes allowed in identifiers
5736 *n* No upper-half codes allowed in identifiers
5737 *w* Wide-character codes (that is, codes greater than 255)
5738 allowed in identifiers
5739 ========== ======================================================
5740
5741 See :ref:`Foreign_Language_Representation` for full details on the
5742 implementation of these character sets.
5743
5744
5745 .. index:: -gnatW (gcc)
5746
5747 :switch:`-gnatW{e}`
5748 Specify the method of encoding for wide characters.
5749 ``e`` is one of the following:
5750
5751 ========== ======================================================
5752 *h* Hex encoding (brackets coding also recognized)
5753 *u* Upper half encoding (brackets encoding also recognized)
5754 *s* Shift/JIS encoding (brackets encoding also recognized)
5755 *e* EUC encoding (brackets encoding also recognized)
5756 *8* UTF-8 encoding (brackets encoding also recognized)
5757 *b* Brackets encoding only (default value)
5758 ========== ======================================================
5759
5760 For full details on these encoding
5761 methods see :ref:`Wide_Character_Encodings`.
5762 Note that brackets coding is always accepted, even if one of the other
5763 options is specified, so for example :switch:`-gnatW8` specifies that both
5764 brackets and UTF-8 encodings will be recognized. The units that are
5765 with'ed directly or indirectly will be scanned using the specified
5766 representation scheme, and so if one of the non-brackets scheme is
5767 used, it must be used consistently throughout the program. However,
5768 since brackets encoding is always recognized, it may be conveniently
5769 used in standard libraries, allowing these libraries to be used with
5770 any of the available coding schemes.
5771
5772 Note that brackets encoding only applies to program text. Within comments,
5773 brackets are considered to be normal graphic characters, and bracket sequences
5774 are never recognized as wide characters.
5775
5776 If no :switch:`-gnatW?` parameter is present, then the default
5777 representation is normally Brackets encoding only. However, if the
5778 first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
5779 byte order mark or BOM for UTF-8), then these three characters are
5780 skipped and the default representation for the file is set to UTF-8.
5781
5782 Note that the wide character representation that is specified (explicitly
5783 or by default) for the main program also acts as the default encoding used
5784 for Wide_Text_IO files if not specifically overridden by a WCEM form
5785 parameter.
5786
5787
5788 When no :switch:`-gnatW?` is specified, then characters (other than wide
5789 characters represented using brackets notation) are treated as 8-bit
5790 Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
5791 and ASCII format effectors (CR, LF, HT, VT). Other lower half control
5792 characters in the range 16#00#..16#1F# are not accepted in program text
5793 or in comments. Upper half control characters (16#80#..16#9F#) are rejected
5794 in program text, but allowed and ignored in comments. Note in particular
5795 that the Next Line (NEL) character whose encoding is 16#85# is not recognized
5796 as an end of line in this default mode. If your source program contains
5797 instances of the NEL character used as a line terminator,
5798 you must use UTF-8 encoding for the whole
5799 source program. In default mode, all lines must be ended by a standard
5800 end of line sequence (CR, CR/LF, or LF).
5801
5802 Note that the convention of simply accepting all upper half characters in
5803 comments means that programs that use standard ASCII for program text, but
5804 UTF-8 encoding for comments are accepted in default mode, providing that the
5805 comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
5806 This is a common mode for many programs with foreign language comments.
5807
5808 .. _File_Naming_Control:
5809
5810 File Naming Control
5811 -------------------
5812
5813 .. index:: -gnatk (gcc)
5814
5815 :switch:`-gnatk{n}`
5816 Activates file name 'krunching'. ``n``, a decimal integer in the range
5817 1-999, indicates the maximum allowable length of a file name (not
5818 including the :file:`.ads` or :file:`.adb` extension). The default is not
5819 to enable file name krunching.
5820
5821 For the source file naming rules, :ref:`File_Naming_Rules`.
5822
5823 .. _Subprogram_Inlining_Control:
5824
5825 Subprogram Inlining Control
5826 ---------------------------
5827
5828 .. index:: -gnatn (gcc)
5829
5830 :switch:`-gnatn[12]`
5831 The ``n`` here is intended to suggest the first syllable of the word 'inline'.
5832 GNAT recognizes and processes ``Inline`` pragmas. However, for inlining to
5833 actually occur, optimization must be enabled and, by default, inlining of
5834 subprograms across units is not performed. If you want to additionally
5835 enable inlining of subprograms specified by pragma ``Inline`` across units,
5836 you must also specify this switch.
5837
5838 In the absence of this switch, GNAT does not attempt inlining across units
5839 and does not access the bodies of subprograms for which ``pragma Inline`` is
5840 specified if they are not in the current unit.
5841
5842 You can optionally specify the inlining level: 1 for moderate inlining across
5843 units, which is a good compromise between compilation times and performances
5844 at run time, or 2 for full inlining across units, which may bring about
5845 longer compilation times. If no inlining level is specified, the compiler will
5846 pick it based on the optimization level: 1 for :switch:`-O1`, :switch:`-O2` or
5847 :switch:`-Os` and 2 for :switch:`-O3`.
5848
5849 If you specify this switch the compiler will access these bodies,
5850 creating an extra source dependency for the resulting object file, and
5851 where possible, the call will be inlined.
5852 For further details on when inlining is possible
5853 see :ref:`Inlining_of_Subprograms`.
5854
5855
5856 .. index:: -gnatN (gcc)
5857
5858 :switch:`-gnatN`
5859 This switch activates front-end inlining which also
5860 generates additional dependencies.
5861
5862 When using a gcc-based back end, then the use of
5863 :switch:`-gnatN` is deprecated, and the use of :switch:`-gnatn` is preferred.
5864 Historically front end inlining was more extensive than the gcc back end
5865 inlining, but that is no longer the case.
5866
5867 .. _Auxiliary_Output_Control:
5868
5869 Auxiliary Output Control
5870 ------------------------
5871
5872 .. index:: -gnatu (gcc)
5873
5874 :switch:`-gnatu`
5875 Print a list of units required by this compilation on :file:`stdout`.
5876 The listing includes all units on which the unit being compiled depends
5877 either directly or indirectly.
5878
5879
5880 .. index:: -pass-exit-codes (gcc)
5881
5882 :switch:`-pass-exit-codes`
5883 If this switch is not used, the exit code returned by ``gcc`` when
5884 compiling multiple files indicates whether all source files have
5885 been successfully used to generate object files or not.
5886
5887 When :switch:`-pass-exit-codes` is used, ``gcc`` exits with an extended
5888 exit status and allows an integrated development environment to better
5889 react to a compilation failure. Those exit status are:
5890
5891 ========== ======================================================
5892 *5* There was an error in at least one source file.
5893 *3* At least one source file did not generate an object file.
5894 *2* The compiler died unexpectedly (internal error for example).
5895 *0* An object file has been generated for every source file.
5896 ========== ======================================================
5897
5898 .. _Debugging_Control:
5899
5900 Debugging Control
5901 -----------------
5902
5903 .. index:: Debugging options
5904
5905
5906 .. index:: -gnatd (gcc)
5907
5908 :switch:`-gnatd{x}`
5909 Activate internal debugging switches. ``x`` is a letter or digit, or
5910 string of letters or digits, which specifies the type of debugging
5911 outputs desired. Normally these are used only for internal development
5912 or system debugging purposes. You can find full documentation for these
5913 switches in the body of the ``Debug`` unit in the compiler source
5914 file :file:`debug.adb`.
5915
5916
5917 .. index:: -gnatG (gcc)
5918
5919 :switch:`-gnatG[={nn}]`
5920 This switch causes the compiler to generate auxiliary output containing
5921 a pseudo-source listing of the generated expanded code. Like most Ada
5922 compilers, GNAT works by first transforming the high level Ada code into
5923 lower level constructs. For example, tasking operations are transformed
5924 into calls to the tasking run-time routines. A unique capability of GNAT
5925 is to list this expanded code in a form very close to normal Ada source.
5926 This is very useful in understanding the implications of various Ada
5927 usage on the efficiency of the generated code. There are many cases in
5928 Ada (e.g., the use of controlled types), where simple Ada statements can
5929 generate a lot of run-time code. By using :switch:`-gnatG` you can identify
5930 these cases, and consider whether it may be desirable to modify the coding
5931 approach to improve efficiency.
5932
5933 The optional parameter ``nn`` if present after -gnatG specifies an
5934 alternative maximum line length that overrides the normal default of 72.
5935 This value is in the range 40-999999, values less than 40 being silently
5936 reset to 40. The equal sign is optional.
5937
5938 The format of the output is very similar to standard Ada source, and is
5939 easily understood by an Ada programmer. The following special syntactic
5940 additions correspond to low level features used in the generated code that
5941 do not have any exact analogies in pure Ada source form. The following
5942 is a partial list of these special constructions. See the spec
5943 of package ``Sprint`` in file :file:`sprint.ads` for a full list.
5944
5945 .. index:: -gnatL (gcc)
5946
5947 If the switch :switch:`-gnatL` is used in conjunction with
5948 :switch:`-gnatG`, then the original source lines are interspersed
5949 in the expanded source (as comment lines with the original line number).
5950
5951 :samp:`new {xxx} [storage_pool = {yyy}]`
5952 Shows the storage pool being used for an allocator.
5953
5954
5955 :samp:`at end {procedure-name};`
5956 Shows the finalization (cleanup) procedure for a scope.
5957
5958
5959 :samp:`(if {expr} then {expr} else {expr})`
5960 Conditional expression equivalent to the ``x?y:z`` construction in C.
5961
5962
5963 :samp:`{target}^({source})`
5964 A conversion with floating-point truncation instead of rounding.
5965
5966
5967 :samp:`{target}?({source})`
5968 A conversion that bypasses normal Ada semantic checking. In particular
5969 enumeration types and fixed-point types are treated simply as integers.
5970
5971
5972 :samp:`{target}?^({source})`
5973 Combines the above two cases.
5974
5975
5976 :samp:`{x} #/ {y}`
5977
5978 :samp:`{x} #mod {y}`
5979
5980 :samp:`{x} # {y}`
5981
5982 :samp:`{x} #rem {y}`
5983 A division or multiplication of fixed-point values which are treated as
5984 integers without any kind of scaling.
5985
5986
5987 :samp:`free {expr} [storage_pool = {xxx}]`
5988 Shows the storage pool associated with a ``free`` statement.
5989
5990
5991 :samp:`[subtype or type declaration]`
5992 Used to list an equivalent declaration for an internally generated
5993 type that is referenced elsewhere in the listing.
5994
5995
5996 :samp:`freeze {type-name} [{actions}]`
5997 Shows the point at which ``type-name`` is frozen, with possible
5998 associated actions to be performed at the freeze point.
5999
6000
6001 :samp:`reference {itype}`
6002 Reference (and hence definition) to internal type ``itype``.
6003
6004
6005 :samp:`{function-name}! ({arg}, {arg}, {arg})`
6006 Intrinsic function call.
6007
6008
6009 :samp:`{label-name} : label`
6010 Declaration of label ``labelname``.
6011
6012
6013 :samp:`#$ {subprogram-name}`
6014 An implicit call to a run-time support routine
6015 (to meet the requirement of H.3.1(9) in a
6016 convenient manner).
6017
6018
6019 :samp:`{expr} && {expr} && {expr} ... && {expr}`
6020 A multiple concatenation (same effect as ``expr`` & ``expr`` &
6021 ``expr``, but handled more efficiently).
6022
6023
6024 :samp:`[constraint_error]`
6025 Raise the ``Constraint_Error`` exception.
6026
6027
6028 :samp:`{expression}'reference`
6029 A pointer to the result of evaluating {expression}.
6030
6031
6032 :samp:`{target-type}!({source-expression})`
6033 An unchecked conversion of ``source-expression`` to ``target-type``.
6034
6035
6036 :samp:`[{numerator}/{denominator}]`
6037 Used to represent internal real literals (that) have no exact
6038 representation in base 2-16 (for example, the result of compile time
6039 evaluation of the expression 1.0/27.0).
6040
6041
6042 .. index:: -gnatD (gcc)
6043
6044 :switch:`-gnatD[=nn]`
6045 When used in conjunction with :switch:`-gnatG`, this switch causes
6046 the expanded source, as described above for
6047 :switch:`-gnatG` to be written to files with names
6048 :file:`xxx.dg`, where :file:`xxx` is the normal file name,
6049 instead of to the standard output file. For
6050 example, if the source file name is :file:`hello.adb`, then a file
6051 :file:`hello.adb.dg` will be written. The debugging
6052 information generated by the ``gcc`` :switch:`-g` switch
6053 will refer to the generated :file:`xxx.dg` file. This allows
6054 you to do source level debugging using the generated code which is
6055 sometimes useful for complex code, for example to find out exactly
6056 which part of a complex construction raised an exception. This switch
6057 also suppresses generation of cross-reference information (see
6058 :switch:`-gnatx`) since otherwise the cross-reference information
6059 would refer to the :file:`.dg` file, which would cause
6060 confusion since this is not the original source file.
6061
6062 Note that :switch:`-gnatD` actually implies :switch:`-gnatG`
6063 automatically, so it is not necessary to give both options.
6064 In other words :switch:`-gnatD` is equivalent to :switch:`-gnatDG`).
6065
6066 .. index:: -gnatL (gcc)
6067
6068 If the switch :switch:`-gnatL` is used in conjunction with
6069 :switch:`-gnatDG`, then the original source lines are interspersed
6070 in the expanded source (as comment lines with the original line number).
6071
6072 The optional parameter ``nn`` if present after -gnatD specifies an
6073 alternative maximum line length that overrides the normal default of 72.
6074 This value is in the range 40-999999, values less than 40 being silently
6075 reset to 40. The equal sign is optional.
6076
6077
6078 .. index:: -gnatr (gcc)
6079 .. index:: pragma Restrictions
6080
6081 :switch:`-gnatr`
6082 This switch causes pragma Restrictions to be treated as Restriction_Warnings
6083 so that violation of restrictions causes warnings rather than illegalities.
6084 This is useful during the development process when new restrictions are added
6085 or investigated. The switch also causes pragma Profile to be treated as
6086 Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
6087 restriction warnings rather than restrictions.
6088
6089
6090 .. index:: -gnatR (gcc)
6091
6092 :switch:`-gnatR[0|1|2|3|4][e][j][m][s]`
6093 This switch controls output from the compiler of a listing showing
6094 representation information for declared types, objects and subprograms.
6095 For :switch:`-gnatR0`, no information is output (equivalent to omitting
6096 the :switch:`-gnatR` switch). For :switch:`-gnatR1` (which is the default,
6097 so :switch:`-gnatR` with no parameter has the same effect), size and
6098 alignment information is listed for declared array and record types.
6099
6100 For :switch:`-gnatR2`, size and alignment information is listed for all
6101 declared types and objects. The ``Linker_Section`` is also listed for any
6102 entity for which the ``Linker_Section`` is set explicitly or implicitly (the
6103 latter case occurs for objects of a type for which a ``Linker_Section``
6104 is set).
6105
6106 For :switch:`-gnatR3`, symbolic expressions for values that are computed
6107 at run time for records are included. These symbolic expressions have
6108 a mostly obvious format with #n being used to represent the value of the
6109 n'th discriminant. See source files :file:`repinfo.ads/adb` in the
6110 GNAT sources for full details on the format of :switch:`-gnatR3` output.
6111
6112 For :switch:`-gnatR4`, information for relevant compiler-generated types
6113 is also listed, i.e. when they are structurally part of other declared
6114 types and objects.
6115
6116 If the switch is followed by an ``e`` (e.g. :switch:`-gnatR2e`), then
6117 extended representation information for record sub-components of records
6118 is included.
6119
6120 If the switch is followed by an ``m`` (e.g. :switch:`-gnatRm`), then
6121 subprogram conventions and parameter passing mechanisms for all the
6122 subprograms are included.
6123
6124 If the switch is followed by a ``j`` (e.g., :switch:`-gnatRj`), then
6125 the output is in the JSON data interchange format specified by the
6126 ECMA-404 standard. The semantic description of this JSON output is
6127 available in the specification of the Repinfo unit present in the
6128 compiler sources.
6129
6130 If the switch is followed by an ``s`` (e.g., :switch:`-gnatR3s`), then
6131 the output is to a file with the name :file:`file.rep` where ``file`` is
6132 the name of the corresponding source file, except if ``j`` is also
6133 specified, in which case the file name is :file:`file.json`.
6134
6135 Note that it is possible for record components to have zero size. In
6136 this case, the component clause uses an obvious extension of permitted
6137 Ada syntax, for example ``at 0 range 0 .. -1``.
6138
6139
6140 .. index:: -gnatS (gcc)
6141
6142 :switch:`-gnatS`
6143 The use of the switch :switch:`-gnatS` for an
6144 Ada compilation will cause the compiler to output a
6145 representation of package Standard in a form very
6146 close to standard Ada. It is not quite possible to
6147 do this entirely in standard Ada (since new
6148 numeric base types cannot be created in standard
6149 Ada), but the output is easily
6150 readable to any Ada programmer, and is useful to
6151 determine the characteristics of target dependent
6152 types in package Standard.
6153
6154
6155 .. index:: -gnatx (gcc)
6156
6157 :switch:`-gnatx`
6158 Normally the compiler generates full cross-referencing information in
6159 the :file:`ALI` file. This information is used by a number of tools.
6160 The :switch:`-gnatx` switch suppresses this information. This saves some space
6161 and may slightly speed up compilation, but means that tools depending
6162 on this information cannot be used.
6163
6164
6165 .. index:: -fgnat-encodings (gcc)
6166
6167 :switch:`-fgnat-encodings=[all|gdb|minimal]`
6168 This switch controls the balance between GNAT encodings and standard DWARF
6169 emitted in the debug information.
6170
6171 Historically, old debug formats like stabs were not powerful enough to
6172 express some Ada types (for instance, variant records or fixed-point types).
6173 To work around this, GNAT introduced proprietary encodings that embed the
6174 missing information ("GNAT encodings").
6175
6176 Recent versions of the DWARF debug information format are now able to
6177 correctly describe most of these Ada constructs ("standard DWARF"). As
6178 third-party tools started to use this format, GNAT has been enhanced to
6179 generate it. However, most tools (including GDB) are still relying on GNAT
6180 encodings.
6181
6182 To support all tools, GNAT needs to be versatile about the balance between
6183 generation of GNAT encodings and standard DWARF. This is what
6184 :switch:`-fgnat-encodings` is about.
6185
6186 * ``=all``: Emit all GNAT encodings, and then emit as much standard DWARF as
6187 possible so it does not conflict with GNAT encodings.
6188 * ``=gdb``: Emit as much standard DWARF as possible as long as the current
6189 GDB handles it. Emit GNAT encodings for the rest.
6190 * ``=minimal``: Emit as much standard DWARF as possible and emit GNAT
6191 encodings for the rest.
6192
6193
6194 .. _Exception_Handling_Control:
6195
6196 Exception Handling Control
6197 --------------------------
6198
6199 GNAT uses two methods for handling exceptions at run time. The
6200 ``setjmp/longjmp`` method saves the context when entering
6201 a frame with an exception handler. Then when an exception is
6202 raised, the context can be restored immediately, without the
6203 need for tracing stack frames. This method provides very fast
6204 exception propagation, but introduces significant overhead for
6205 the use of exception handlers, even if no exception is raised.
6206
6207 The other approach is called 'zero cost' exception handling.
6208 With this method, the compiler builds static tables to describe
6209 the exception ranges. No dynamic code is required when entering
6210 a frame containing an exception handler. When an exception is
6211 raised, the tables are used to control a back trace of the
6212 subprogram invocation stack to locate the required exception
6213 handler. This method has considerably poorer performance for
6214 the propagation of exceptions, but there is no overhead for
6215 exception handlers if no exception is raised. Note that in this
6216 mode and in the context of mixed Ada and C/C++ programming,
6217 to propagate an exception through a C/C++ code, the C/C++ code
6218 must be compiled with the :switch:`-funwind-tables` GCC's
6219 option.
6220
6221 The following switches may be used to control which of the
6222 two exception handling methods is used.
6223
6224
6225
6226 .. index:: --RTS=sjlj (gnatmake)
6227
6228 :switch:`--RTS=sjlj`
6229 This switch causes the setjmp/longjmp run-time (when available) to be used
6230 for exception handling. If the default
6231 mechanism for the target is zero cost exceptions, then
6232 this switch can be used to modify this default, and must be
6233 used for all units in the partition.
6234 This option is rarely used. One case in which it may be
6235 advantageous is if you have an application where exception
6236 raising is common and the overall performance of the
6237 application is improved by favoring exception propagation.
6238
6239
6240 .. index:: --RTS=zcx (gnatmake)
6241 .. index:: Zero Cost Exceptions
6242
6243 :switch:`--RTS=zcx`
6244 This switch causes the zero cost approach to be used
6245 for exception handling. If this is the default mechanism for the
6246 target (see below), then this switch is unneeded. If the default
6247 mechanism for the target is setjmp/longjmp exceptions, then
6248 this switch can be used to modify this default, and must be
6249 used for all units in the partition.
6250 This option can only be used if the zero cost approach
6251 is available for the target in use, otherwise it will generate an error.
6252
6253 The same option :switch:`--RTS` must be used both for ``gcc``
6254 and ``gnatbind``. Passing this option to ``gnatmake``
6255 (:ref:`Switches_for_gnatmake`) will ensure the required consistency
6256 through the compilation and binding steps.
6257
6258 .. _Units_to_Sources_Mapping_Files:
6259
6260 Units to Sources Mapping Files
6261 ------------------------------
6262
6263
6264
6265 .. index:: -gnatem (gcc)
6266
6267 :switch:`-gnatem={path}`
6268 A mapping file is a way to communicate to the compiler two mappings:
6269 from unit names to file names (without any directory information) and from
6270 file names to path names (with full directory information). These mappings
6271 are used by the compiler to short-circuit the path search.
6272
6273 The use of mapping files is not required for correct operation of the
6274 compiler, but mapping files can improve efficiency, particularly when
6275 sources are read over a slow network connection. In normal operation,
6276 you need not be concerned with the format or use of mapping files,
6277 and the :switch:`-gnatem` switch is not a switch that you would use
6278 explicitly. It is intended primarily for use by automatic tools such as
6279 ``gnatmake`` running under the project file facility. The
6280 description here of the format of mapping files is provided
6281 for completeness and for possible use by other tools.
6282
6283 A mapping file is a sequence of sets of three lines. In each set, the
6284 first line is the unit name, in lower case, with ``%s`` appended
6285 for specs and ``%b`` appended for bodies; the second line is the
6286 file name; and the third line is the path name.
6287
6288 Example::
6289
6290 main%b
6291 main.2.ada
6292 /gnat/project1/sources/main.2.ada
6293
6294
6295 When the switch :switch:`-gnatem` is specified, the compiler will
6296 create in memory the two mappings from the specified file. If there is
6297 any problem (nonexistent file, truncated file or duplicate entries),
6298 no mapping will be created.
6299
6300 Several :switch:`-gnatem` switches may be specified; however, only the
6301 last one on the command line will be taken into account.
6302
6303 When using a project file, ``gnatmake`` creates a temporary
6304 mapping file and communicates it to the compiler using this switch.
6305
6306
6307 .. _Code_Generation_Control:
6308
6309 Code Generation Control
6310 -----------------------
6311
6312 The GCC technology provides a wide range of target dependent
6313 :switch:`-m` switches for controlling
6314 details of code generation with respect to different versions of
6315 architectures. This includes variations in instruction sets (e.g.,
6316 different members of the power pc family), and different requirements
6317 for optimal arrangement of instructions (e.g., different members of
6318 the x86 family). The list of available :switch:`-m` switches may be
6319 found in the GCC documentation.
6320
6321 Use of these :switch:`-m` switches may in some cases result in improved
6322 code performance.
6323
6324 The GNAT technology is tested and qualified without any
6325 :switch:`-m` switches,
6326 so generally the most reliable approach is to avoid the use of these
6327 switches. However, we generally expect most of these switches to work
6328 successfully with GNAT, and many customers have reported successful
6329 use of these options.
6330
6331 Our general advice is to avoid the use of :switch:`-m` switches unless
6332 special needs lead to requirements in this area. In particular,
6333 there is no point in using :switch:`-m` switches to improve performance
6334 unless you actually see a performance improvement.
6335
6336
6337 .. _Linker_Switches:
6338
6339 Linker Switches
6340 ===============
6341
6342 Linker switches can be specified after :switch:`-largs` builder switch.
6343
6344 .. index:: -fuse-ld=name
6345
6346 :switch:`-fuse-ld={name}`
6347 Linker to be used. The default is ``bfd`` for :file:`ld.bfd`; ``gold``
6348 (for :file:`ld.gold`) and ``mold`` (for :file:`ld.mold`) are more
6349 recent and faster alternatives, but only available on GNU/Linux
6350 platforms.
6351
6352 .. _Binding_with_gnatbind:
6353
6354 Binding with ``gnatbind``
6355 =========================
6356
6357 .. index:: ! gnatbind
6358
6359 This chapter describes the GNAT binder, ``gnatbind``, which is used
6360 to bind compiled GNAT objects.
6361
6362 The ``gnatbind`` program performs four separate functions:
6363
6364 * Checks that a program is consistent, in accordance with the rules in
6365 Chapter 10 of the Ada Reference Manual. In particular, error
6366 messages are generated if a program uses inconsistent versions of a
6367 given unit.
6368
6369 * Checks that an acceptable order of elaboration exists for the program
6370 and issues an error message if it cannot find an order of elaboration
6371 that satisfies the rules in Chapter 10 of the Ada Language Manual.
6372
6373 * Generates a main program incorporating the given elaboration order.
6374 This program is a small Ada package (body and spec) that
6375 must be subsequently compiled
6376 using the GNAT compiler. The necessary compilation step is usually
6377 performed automatically by ``gnatlink``. The two most important
6378 functions of this program
6379 are to call the elaboration routines of units in an appropriate order
6380 and to call the main program.
6381
6382 * Determines the set of object files required by the given main program.
6383 This information is output in the forms of comments in the generated program,
6384 to be read by the ``gnatlink`` utility used to link the Ada application.
6385
6386 .. _Running_gnatbind:
6387
6388 Running ``gnatbind``
6389 --------------------
6390
6391 The form of the ``gnatbind`` command is
6392
6393 .. code-block:: sh
6394
6395 $ gnatbind [ switches ] mainprog[.ali] [ switches ]
6396
6397
6398 where :file:`mainprog.adb` is the Ada file containing the main program
6399 unit body. ``gnatbind`` constructs an Ada
6400 package in two files whose names are
6401 :file:`b~mainprog.ads`, and :file:`b~mainprog.adb`.
6402 For example, if given the
6403 parameter :file:`hello.ali`, for a main program contained in file
6404 :file:`hello.adb`, the binder output files would be :file:`b~hello.ads`
6405 and :file:`b~hello.adb`.
6406
6407 When doing consistency checking, the binder takes into consideration
6408 any source files it can locate. For example, if the binder determines
6409 that the given main program requires the package ``Pack``, whose
6410 :file:`.ALI`
6411 file is :file:`pack.ali` and whose corresponding source spec file is
6412 :file:`pack.ads`, it attempts to locate the source file :file:`pack.ads`
6413 (using the same search path conventions as previously described for the
6414 ``gcc`` command). If it can locate this source file, it checks that
6415 the time stamps
6416 or source checksums of the source and its references to in :file:`ALI` files
6417 match. In other words, any :file:`ALI` files that mentions this spec must have
6418 resulted from compiling this version of the source file (or in the case
6419 where the source checksums match, a version close enough that the
6420 difference does not matter).
6421
6422 .. index:: Source files, use by binder
6423
6424 The effect of this consistency checking, which includes source files, is
6425 that the binder ensures that the program is consistent with the latest
6426 version of the source files that can be located at bind time. Editing a
6427 source file without compiling files that depend on the source file cause
6428 error messages to be generated by the binder.
6429
6430 For example, suppose you have a main program :file:`hello.adb` and a
6431 package ``P``, from file :file:`p.ads` and you perform the following
6432 steps:
6433
6434 * Enter ``gcc -c hello.adb`` to compile the main program.
6435
6436 * Enter ``gcc -c p.ads`` to compile package ``P``.
6437
6438 * Edit file :file:`p.ads`.
6439
6440 * Enter ``gnatbind hello``.
6441
6442 At this point, the file :file:`p.ali` contains an out-of-date time stamp
6443 because the file :file:`p.ads` has been edited. The attempt at binding
6444 fails, and the binder generates the following error messages:
6445
6446
6447 ::
6448
6449 error: "hello.adb" must be recompiled ("p.ads" has been modified)
6450 error: "p.ads" has been modified and must be recompiled
6451
6452
6453 Now both files must be recompiled as indicated, and then the bind can
6454 succeed, generating a main program. You need not normally be concerned
6455 with the contents of this file, but for reference purposes a sample
6456 binder output file is given in :ref:`Example_of_Binder_Output_File`.
6457
6458 In most normal usage, the default mode of ``gnatbind`` which is to
6459 generate the main package in Ada, as described in the previous section.
6460 In particular, this means that any Ada programmer can read and understand
6461 the generated main program. It can also be debugged just like any other
6462 Ada code provided the :switch:`-g` switch is used for
6463 ``gnatbind`` and ``gnatlink``.
6464
6465 .. _Switches_for_gnatbind:
6466
6467 Switches for ``gnatbind``
6468 -------------------------
6469
6470 The following switches are available with ``gnatbind``; details will
6471 be presented in subsequent sections.
6472
6473
6474 .. index:: --version (gnatbind)
6475
6476 :switch:`--version`
6477 Display Copyright and version, then exit disregarding all other options.
6478
6479
6480 .. index:: --help (gnatbind)
6481
6482 :switch:`--help`
6483 If :switch:`--version` was not used, display usage, then exit disregarding
6484 all other options.
6485
6486
6487 .. index:: -a (gnatbind)
6488
6489 :switch:`-a`
6490 Indicates that, if supported by the platform, the adainit procedure should
6491 be treated as an initialisation routine by the linker (a constructor). This
6492 is intended to be used by the Project Manager to automatically initialize
6493 shared Stand-Alone Libraries.
6494
6495
6496 .. index:: -aO (gnatbind)
6497
6498 :switch:`-aO`
6499 Specify directory to be searched for ALI files.
6500
6501
6502 .. index:: -aI (gnatbind)
6503
6504 :switch:`-aI`
6505 Specify directory to be searched for source file.
6506
6507
6508 .. index:: -A (gnatbind)
6509
6510 :switch:`-A[={filename}]`
6511 Output ALI list (to standard output or to the named file).
6512
6513
6514 .. index:: -b (gnatbind)
6515
6516 :switch:`-b`
6517 Generate brief messages to :file:`stderr` even if verbose mode set.
6518
6519
6520 .. index:: -c (gnatbind)
6521
6522 :switch:`-c`
6523 Check only, no generation of binder output file.
6524
6525
6526 .. index:: -dnn[k|m] (gnatbind)
6527
6528 :switch:`-d{nn}[k|m]`
6529 This switch can be used to change the default task stack size value
6530 to a specified size ``nn``, which is expressed in bytes by default, or
6531 in kilobytes when suffixed with ``k`` or in megabytes when suffixed
6532 with ``m``.
6533 In the absence of a :samp:`[k|m]` suffix, this switch is equivalent,
6534 in effect, to completing all task specs with
6535
6536 .. code-block:: ada
6537
6538 pragma Storage_Size (nn);
6539
6540 When they do not already have such a pragma.
6541
6542
6543 .. index:: -D (gnatbind)
6544
6545 :switch:`-D{nn}[k|m]`
6546 Set the default secondary stack size to ``nn``. The suffix indicates whether
6547 the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
6548 (``m`` suffix).
6549
6550 The secondary stack holds objects of unconstrained types that are returned by
6551 functions, for example unconstrained Strings. The size of the secondary stack
6552 can be dynamic or fixed depending on the target.
6553
6554 For most targets, the secondary stack grows on demand and is implemented as
6555 a chain of blocks in the heap. In this case, the default secondary stack size
6556 determines the initial size of the secondary stack for each task and the
6557 smallest amount the secondary stack can grow by.
6558
6559 For Light, Light-Tasking, and Embedded run-times the size of the secondary
6560 stack is fixed. This switch can be used to change the default size of these
6561 stacks. The default secondary stack size can be overridden on a per-task
6562 basis if individual tasks have different secondary stack requirements. This
6563 is achieved through the Secondary_Stack_Size aspect, which takes the size of
6564 the secondary stack in bytes.
6565
6566 .. index:: -e (gnatbind)
6567
6568 :switch:`-e`
6569 Output complete list of elaboration-order dependencies.
6570
6571
6572 .. index:: -Ea (gnatbind)
6573
6574 :switch:`-Ea`
6575 Store tracebacks in exception occurrences when the target supports it.
6576 The "a" is for "address"; tracebacks will contain hexadecimal addresses,
6577 unless symbolic tracebacks are enabled.
6578
6579 See also the packages ``GNAT.Traceback`` and
6580 ``GNAT.Traceback.Symbolic`` for more information.
6581 Note that on x86 ports, you must not use :switch:`-fomit-frame-pointer`
6582 ``gcc`` option.
6583
6584
6585 .. index:: -Es (gnatbind)
6586
6587 :switch:`-Es`
6588 Store tracebacks in exception occurrences when the target supports it.
6589 The "s" is for "symbolic"; symbolic tracebacks are enabled.
6590
6591
6592 .. index:: -E (gnatbind)
6593
6594 :switch:`-E`
6595 Currently the same as ``-Ea``.
6596
6597
6598 .. index:: -f (gnatbind)
6599
6600 :switch:`-f{elab-order}`
6601 Force elaboration order. For further details see :ref:`Elaboration_Control`
6602 and :ref:`Elaboration_Order_Handling_in_GNAT`.
6603
6604
6605 .. index:: -F (gnatbind)
6606
6607 :switch:`-F`
6608 Force the checks of elaboration flags. ``gnatbind`` does not normally
6609 generate checks of elaboration flags for the main executable, except when
6610 a Stand-Alone Library is used. However, there are cases when this cannot be
6611 detected by gnatbind. An example is importing an interface of a Stand-Alone
6612 Library through a pragma Import and only specifying through a linker switch
6613 this Stand-Alone Library. This switch is used to guarantee that elaboration
6614 flag checks are generated.
6615
6616
6617 .. index:: -h (gnatbind)
6618
6619 :switch:`-h`
6620 Output usage (help) information.
6621
6622
6623 .. index:: -H (gnatbind)
6624
6625 :switch:`-H`
6626 Legacy elaboration order model enabled. For further details see
6627 :ref:`Elaboration_Order_Handling_in_GNAT`.
6628
6629
6630 .. index:: -H32 (gnatbind)
6631
6632 :switch:`-H32`
6633 Use 32-bit allocations for ``__gnat_malloc`` (and thus for access types).
6634 For further details see :ref:`Dynamic_Allocation_Control`.
6635
6636
6637 .. index:: -H64 (gnatbind)
6638 .. index:: __gnat_malloc
6639
6640 :switch:`-H64`
6641 Use 64-bit allocations for ``__gnat_malloc`` (and thus for access types).
6642 For further details see :ref:`Dynamic_Allocation_Control`.
6643
6644
6645 .. index:: -I (gnatbind)
6646
6647 :switch:`-I`
6648 Specify directory to be searched for source and ALI files.
6649
6650
6651 .. index:: -I- (gnatbind)
6652
6653 :switch:`-I-`
6654 Do not look for sources in the current directory where ``gnatbind`` was
6655 invoked, and do not look for ALI files in the directory containing the
6656 ALI file named in the ``gnatbind`` command line.
6657
6658
6659 .. index:: -k (gnatbind)
6660
6661 :switch:`-k`
6662 Disable checking of elaboration flags. When using :switch:`-n`
6663 either explicitly or implicitly, :switch:`-F` is also implied,
6664 unless :switch:`-k` is used. This switch should be used with care
6665 and you should ensure manually that elaboration routines are not called
6666 twice unintentionally.
6667
6668
6669 .. index:: -K (gnatbind)
6670
6671 :switch:`-K`
6672 Give list of linker options specified for link.
6673
6674
6675 .. index:: -l (gnatbind)
6676
6677 :switch:`-l`
6678 Output chosen elaboration order.
6679
6680
6681 .. index:: -L (gnatbind)
6682
6683 :switch:`-L{xxx}`
6684 Bind the units for library building. In this case the ``adainit`` and
6685 ``adafinal`` procedures (:ref:`Binding_with_Non-Ada_Main_Programs`)
6686 are renamed to :samp:`{xxx}init` and
6687 :samp:`{xxx}final`.
6688 Implies -n.
6689 (:ref:`GNAT_and_Libraries`, for more details.)
6690
6691
6692 .. index:: -M (gnatbind)
6693
6694 :switch:`-M{xyz}`
6695 Rename generated main program from main to xyz. This option is
6696 supported on cross environments only.
6697
6698 .. index:: -m (gnatbind)
6699
6700 :switch:`-m{n}`
6701 Limit number of detected errors or warnings to ``n``, where ``n`` is
6702 in the range 1..999999. The default value if no switch is
6703 given is 9999. If the number of warnings reaches this limit, then a
6704 message is output and further warnings are suppressed, the bind
6705 continues in this case. If the number of errors reaches this
6706 limit, then a message is output and the bind is abandoned.
6707 A value of zero means that no limit is enforced. The equal
6708 sign is optional.
6709
6710 .. index:: -minimal (gnatbind)
6711
6712 :switch:`-minimal`
6713 Generate a binder file suitable for space-constrained applications. When
6714 active, binder-generated objects not required for program operation are no
6715 longer generated. **Warning:** this option comes with the following
6716 limitations:
6717
6718 * Starting the program's execution in the debugger will cause it to
6719 stop at the start of the ``main`` function instead of the main subprogram.
6720 This can be worked around by manually inserting a breakpoint on that
6721 subprogram and resuming the program's execution until reaching that breakpoint.
6722 * Programs using GNAT.Compiler_Version will not link.
6723
6724 .. index:: -n (gnatbind)
6725
6726 :switch:`-n`
6727 No main program.
6728
6729
6730 .. index:: -nostdinc (gnatbind)
6731
6732 :switch:`-nostdinc`
6733 Do not look for sources in the system default directory.
6734
6735
6736 .. index:: -nostdlib (gnatbind)
6737
6738 :switch:`-nostdlib`
6739 Do not look for library files in the system default directory.
6740
6741
6742 .. index:: --RTS (gnatbind)
6743
6744 :switch:`--RTS={rts-path}`
6745 Specifies the default location of the run-time library. Same meaning as the
6746 equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
6747
6748 .. index:: -o (gnatbind)
6749
6750 :switch:`-o {file}`
6751 Name the output file ``file`` (default is :file:`b~{xxx}.adb`).
6752 Note that if this option is used, then linking must be done manually,
6753 gnatlink cannot be used.
6754
6755
6756 .. index:: -O (gnatbind)
6757
6758 :switch:`-O[={filename}]`
6759 Output object list (to standard output or to the named file).
6760
6761
6762 .. index:: -p (gnatbind)
6763
6764 :switch:`-p`
6765 Pessimistic (worst-case) elaboration order.
6766
6767
6768 .. index:: -P (gnatbind)
6769
6770 :switch:`-P`
6771 Generate binder file suitable for CodePeer.
6772
6773
6774 .. index:: -Q (gnatbind)
6775
6776 :switch:`-Q{nnn}`
6777 Generate ``nnn`` additional default-sized secondary stacks.
6778
6779 Tasks declared at the library level that use default-size secondary stacks
6780 have their secondary stacks allocated from a pool of stacks generated by
6781 gnatbind. This allows the default secondary stack size to be quickly changed
6782 by rebinding the application.
6783
6784 While the binder sizes this pool to match the number of such tasks defined in
6785 the application, the pool size may need to be increased with the :switch:`-Q`
6786 switch to accommodate foreign threads registered with the Light run-time. For
6787 more information, please see the *The Primary and Secondary Stack* chapter in
6788 the *GNAT User’s Guide Supplement for Cross Platforms*.
6789
6790
6791 .. index:: -R (gnatbind)
6792
6793 :switch:`-R`
6794 Output closure source list, which includes all non-run-time units that are
6795 included in the bind.
6796
6797
6798 .. index:: -Ra (gnatbind)
6799
6800 :switch:`-Ra`
6801 Like :switch:`-R` but the list includes run-time units.
6802
6803
6804 .. index:: -s (gnatbind)
6805
6806 :switch:`-s`
6807 Require all source files to be present.
6808
6809
6810 .. index:: -S (gnatbind)
6811
6812 :switch:`-S{xxx}`
6813 Specifies the value to be used when detecting uninitialized scalar
6814 objects with pragma Initialize_Scalars.
6815 The ``xxx`` string specified with the switch is one of:
6816
6817 * ``in`` for an invalid value.
6818
6819 If zero is invalid for the discrete type in question,
6820 then the scalar value is set to all zero bits.
6821 For signed discrete types, the largest possible negative value of
6822 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6823 For unsigned discrete types, the underlying scalar value is set to all
6824 one bits. For floating-point types, a NaN value is set
6825 (see body of package System.Scalar_Values for exact values).
6826
6827 * ``lo`` for low value.
6828
6829 If zero is invalid for the discrete type in question,
6830 then the scalar value is set to all zero bits.
6831 For signed discrete types, the largest possible negative value of
6832 the underlying scalar is set (i.e. a one bit followed by all zero bits).
6833 For unsigned discrete types, the underlying scalar value is set to all
6834 zero bits. For floating-point, a small value is set
6835 (see body of package System.Scalar_Values for exact values).
6836
6837 * ``hi`` for high value.
6838
6839 If zero is invalid for the discrete type in question,
6840 then the scalar value is set to all one bits.
6841 For signed discrete types, the largest possible positive value of
6842 the underlying scalar is set (i.e. a zero bit followed by all one bits).
6843 For unsigned discrete types, the underlying scalar value is set to all
6844 one bits. For floating-point, a large value is set
6845 (see body of package System.Scalar_Values for exact values).
6846
6847 * ``xx`` for hex value (two hex digits).
6848
6849 The underlying scalar is set to a value consisting of repeated bytes, whose
6850 value corresponds to the given value. For example if ``BF`` is given,
6851 then a 32-bit scalar value will be set to the bit pattern ``16#BFBFBFBF#``.
6852
6853 .. index:: GNAT_INIT_SCALARS
6854
6855 In addition, you can specify :switch:`-Sev` to indicate that the value is
6856 to be set at run time. In this case, the program will look for an environment
6857 variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where ``yy`` is one
6858 of :samp:`in/lo/hi/{xx}` with the same meanings as above.
6859 If no environment variable is found, or if it does not have a valid value,
6860 then the default is ``in`` (invalid values).
6861
6862 .. index:: -static (gnatbind)
6863
6864 :switch:`-static`
6865 Link against a static GNAT run-time.
6866
6867
6868 .. index:: -shared (gnatbind)
6869
6870 :switch:`-shared`
6871 Link against a shared GNAT run-time when available.
6872
6873
6874 .. index:: -t (gnatbind)
6875
6876 :switch:`-t`
6877 Tolerate time stamp and other consistency errors.
6878
6879
6880 .. index:: -T (gnatbind)
6881
6882 :switch:`-T{n}`
6883 Set the time slice value to ``n`` milliseconds. If the system supports
6884 the specification of a specific time slice value, then the indicated value
6885 is used. If the system does not support specific time slice values, but
6886 does support some general notion of round-robin scheduling, then any
6887 nonzero value will activate round-robin scheduling.
6888
6889 A value of zero is treated specially. It turns off time
6890 slicing, and in addition, indicates to the tasking run-time that the
6891 semantics should match as closely as possible the Annex D
6892 requirements of the Ada RM, and in particular sets the default
6893 scheduling policy to ``FIFO_Within_Priorities``.
6894
6895
6896 .. index:: -u (gnatbind)
6897
6898 :switch:`-u{n}`
6899 Enable dynamic stack usage, with ``n`` results stored and displayed
6900 at program termination. A result is generated when a task
6901 terminates. Results that can't be stored are displayed on the fly, at
6902 task termination. This option is currently not supported on Itanium
6903 platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.)
6904
6905
6906 .. index:: -v (gnatbind)
6907
6908 :switch:`-v`
6909 Verbose mode. Write error messages, header, summary output to
6910 :file:`stdout`.
6911
6912
6913 .. index:: -V (gnatbind)
6914
6915 :switch:`-V{key}={value}`
6916 Store the given association of ``key`` to ``value`` in the bind environment.
6917 Values stored this way can be retrieved at run time using
6918 ``GNAT.Bind_Environment``.
6919
6920
6921 .. index:: -w (gnatbind)
6922
6923 :switch:`-w{x}`
6924 Warning mode; ``x`` = s/e for suppress/treat as error.
6925
6926
6927 .. index:: -Wx (gnatbind)
6928
6929 :switch:`-Wx{e}`
6930 Override default wide character encoding for standard Text_IO files.
6931
6932
6933 .. index:: -x (gnatbind)
6934
6935 :switch:`-x`
6936 Exclude source files (check object consistency only).
6937
6938
6939 .. index:: -xdr (gnatbind)
6940
6941 :switch:`-xdr`
6942 Use the target-independent XDR protocol for stream oriented attributes
6943 instead of the default implementation which is based on direct binary
6944 representations and is therefore target-and endianness-dependent.
6945 However it does not support 128-bit integer types and the exception
6946 ``Ada.IO_Exceptions.Device_Error`` is raised if any attempt is made
6947 at streaming 128-bit integer types with it.
6948
6949
6950 .. index:: -Xnnn (gnatbind)
6951
6952 :switch:`-X{nnn}`
6953 Set default exit status value, normally 0 for POSIX compliance.
6954
6955
6956 .. index:: -y (gnatbind)
6957
6958 :switch:`-y`
6959 Enable leap seconds support in ``Ada.Calendar`` and its children.
6960
6961
6962 .. index:: -z (gnatbind)
6963
6964 :switch:`-z`
6965 No main subprogram.
6966
6967 You may obtain this listing of switches by running ``gnatbind`` with
6968 no arguments.
6969
6970
6971 .. _Consistency-Checking_Modes:
6972
6973 Consistency-Checking Modes
6974 ^^^^^^^^^^^^^^^^^^^^^^^^^^
6975
6976 As described earlier, by default ``gnatbind`` checks
6977 that object files are consistent with one another and are consistent
6978 with any source files it can locate. The following switches control binder
6979 access to sources.
6980
6981
6982 .. index:: -s (gnatbind)
6983
6984 :switch:`-s`
6985 Require source files to be present. In this mode, the binder must be
6986 able to locate all source files that are referenced, in order to check
6987 their consistency. In normal mode, if a source file cannot be located it
6988 is simply ignored. If you specify this switch, a missing source
6989 file is an error.
6990
6991
6992 .. index:: -Wx (gnatbind)
6993
6994 :switch:`-Wx{e}`
6995 Override default wide character encoding for standard Text_IO files.
6996 Normally the default wide character encoding method used for standard
6997 [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for
6998 the main source input (see description of switch
6999 :switch:`-gnatWx` for the compiler). The
7000 use of this switch for the binder (which has the same set of
7001 possible arguments) overrides this default as specified.
7002
7003
7004 .. index:: -x (gnatbind)
7005
7006 :switch:`-x`
7007 Exclude source files. In this mode, the binder only checks that ALI
7008 files are consistent with one another. Source files are not accessed.
7009 The binder runs faster in this mode, and there is still a guarantee that
7010 the resulting program is self-consistent.
7011 If a source file has been edited since it was last compiled, and you
7012 specify this switch, the binder will not detect that the object
7013 file is out of date with respect to the source file. Note that this is the
7014 mode that is automatically used by ``gnatmake`` because in this
7015 case the checking against sources has already been performed by
7016 ``gnatmake`` in the course of compilation (i.e., before binding).
7017
7018
7019 .. _Binder_Error_Message_Control:
7020
7021 Binder Error Message Control
7022 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7023
7024 The following switches provide control over the generation of error
7025 messages from the binder:
7026
7027
7028
7029 .. index:: -v (gnatbind)
7030
7031 :switch:`-v`
7032 Verbose mode. In the normal mode, brief error messages are generated to
7033 :file:`stderr`. If this switch is present, a header is written
7034 to :file:`stdout` and any error messages are directed to :file:`stdout`.
7035 All that is written to :file:`stderr` is a brief summary message.
7036
7037
7038 .. index:: -b (gnatbind)
7039
7040 :switch:`-b`
7041 Generate brief error messages to :file:`stderr` even if verbose mode is
7042 specified. This is relevant only when used with the
7043 :switch:`-v` switch.
7044
7045
7046 .. index:: -m (gnatbind)
7047
7048 :switch:`-m{n}`
7049 Limits the number of error messages to ``n``, a decimal integer in the
7050 range 1-999. The binder terminates immediately if this limit is reached.
7051
7052
7053 .. index:: -M (gnatbind)
7054
7055 :switch:`-M{xxx}`
7056 Renames the generated main program from ``main`` to ``xxx``.
7057 This is useful in the case of some cross-building environments, where
7058 the actual main program is separate from the one generated
7059 by ``gnatbind``.
7060
7061
7062 .. index:: -ws (gnatbind)
7063 .. index:: Warnings
7064
7065 :switch:`-ws`
7066 Suppress all warning messages.
7067
7068
7069 .. index:: -we (gnatbind)
7070
7071 :switch:`-we`
7072 Treat any warning messages as fatal errors.
7073
7074
7075 .. index:: -t (gnatbind)
7076 .. index:: Time stamp checks, in binder
7077 .. index:: Binder consistency checks
7078 .. index:: Consistency checks, in binder
7079
7080 :switch:`-t`
7081 The binder performs a number of consistency checks including:
7082
7083
7084 * Check that time stamps of a given source unit are consistent
7085
7086 * Check that checksums of a given source unit are consistent
7087
7088 * Check that consistent versions of ``GNAT`` were used for compilation
7089
7090 * Check consistency of configuration pragmas as required
7091
7092 Normally failure of such checks, in accordance with the consistency
7093 requirements of the Ada Reference Manual, causes error messages to be
7094 generated which abort the binder and prevent the output of a binder
7095 file and subsequent link to obtain an executable.
7096
7097 The :switch:`-t` switch converts these error messages
7098 into warnings, so that
7099 binding and linking can continue to completion even in the presence of such
7100 errors. The result may be a failed link (due to missing symbols), or a
7101 non-functional executable which has undefined semantics.
7102
7103 .. note::
7104
7105 This means that :switch:`-t` should be used only in unusual situations,
7106 with extreme care.
7107
7108 .. _Elaboration_Control:
7109
7110 Elaboration Control
7111 ^^^^^^^^^^^^^^^^^^^
7112
7113 The following switches provide additional control over the elaboration
7114 order. For further details see :ref:`Elaboration_Order_Handling_in_GNAT`.
7115
7116
7117 .. index:: -f (gnatbind)
7118
7119 :switch:`-f{elab-order}`
7120 Force elaboration order.
7121
7122 ``elab-order`` should be the name of a "forced elaboration order file", that
7123 is, a text file containing library item names, one per line. A name of the
7124 form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
7125 name of the form "some.unit%b" or "some.unit (body)" denotes the body of
7126 Some.Unit. Each pair of lines is taken to mean that there is an elaboration
7127 dependence of the second line on the first. For example, if the file
7128 contains:
7129
7130 .. code-block:: ada
7131
7132 this (spec)
7133 this (body)
7134 that (spec)
7135 that (body)
7136
7137 then the spec of This will be elaborated before the body of This, and the
7138 body of This will be elaborated before the spec of That, and the spec of That
7139 will be elaborated before the body of That. The first and last of these three
7140 dependences are already required by Ada rules, so this file is really just
7141 forcing the body of This to be elaborated before the spec of That.
7142
7143 The given order must be consistent with Ada rules, or else ``gnatbind`` will
7144 give elaboration cycle errors. For example, if you say x (body) should be
7145 elaborated before x (spec), there will be a cycle, because Ada rules require
7146 x (spec) to be elaborated before x (body); you can't have the spec and body
7147 both elaborated before each other.
7148
7149 If you later add "with That;" to the body of This, there will be a cycle, in
7150 which case you should erase either "this (body)" or "that (spec)" from the
7151 above forced elaboration order file.
7152
7153 Blank lines and Ada-style comments are ignored. Unit names that do not exist
7154 in the program are ignored. Units in the GNAT predefined library are also
7155 ignored.
7156
7157
7158 .. index:: -p (gnatbind)
7159
7160 :switch:`-p`
7161 Pessimistic elaboration order
7162
7163 This switch is only applicable to the pre-20.x legacy elaboration models.
7164 The post-20.x elaboration model uses a more informed approach of ordering
7165 the units.
7166
7167 Normally the binder attempts to choose an elaboration order that is likely to
7168 minimize the likelihood of an elaboration order error resulting in raising a
7169 ``Program_Error`` exception. This switch reverses the action of the binder,
7170 and requests that it deliberately choose an order that is likely to maximize
7171 the likelihood of an elaboration error. This is useful in ensuring
7172 portability and avoiding dependence on accidental fortuitous elaboration
7173 ordering.
7174
7175 Normally it only makes sense to use the :switch:`-p` switch if dynamic
7176 elaboration checking is used (:switch:`-gnatE` switch used for compilation).
7177 This is because in the default static elaboration mode, all necessary
7178 ``Elaborate`` and ``Elaborate_All`` pragmas are implicitly inserted.
7179 These implicit pragmas are still respected by the binder in :switch:`-p`
7180 mode, so a safe elaboration order is assured.
7181
7182 Note that :switch:`-p` is not intended for production use; it is more for
7183 debugging/experimental use.
7184
7185 .. _Output_Control:
7186
7187 Output Control
7188 ^^^^^^^^^^^^^^
7189
7190 The following switches allow additional control over the output
7191 generated by the binder.
7192
7193
7194 .. index:: -c (gnatbind)
7195
7196 :switch:`-c`
7197 Check only. Do not generate the binder output file. In this mode the
7198 binder performs all error checks but does not generate an output file.
7199
7200
7201 .. index:: -e (gnatbind)
7202
7203 :switch:`-e`
7204 Output complete list of elaboration-order dependencies, showing the
7205 reason for each dependency. This output can be rather extensive but may
7206 be useful in diagnosing problems with elaboration order. The output is
7207 written to :file:`stdout`.
7208
7209
7210 .. index:: -h (gnatbind)
7211
7212 :switch:`-h`
7213 Output usage information. The output is written to :file:`stdout`.
7214
7215
7216 .. index:: -K (gnatbind)
7217
7218 :switch:`-K`
7219 Output linker options to :file:`stdout`. Includes library search paths,
7220 contents of pragmas Ident and Linker_Options, and libraries added
7221 by ``gnatbind``.
7222
7223
7224 .. index:: -l (gnatbind)
7225
7226 :switch:`-l`
7227 Output chosen elaboration order. The output is written to :file:`stdout`.
7228
7229
7230 .. index:: -O (gnatbind)
7231
7232 :switch:`-O`
7233 Output full names of all the object files that must be linked to provide
7234 the Ada component of the program. The output is written to :file:`stdout`.
7235 This list includes the files explicitly supplied and referenced by the user
7236 as well as implicitly referenced run-time unit files. The latter are
7237 omitted if the corresponding units reside in shared libraries. The
7238 directory names for the run-time units depend on the system configuration.
7239
7240
7241 .. index:: -o (gnatbind)
7242
7243 :switch:`-o {file}`
7244 Set name of output file to ``file`` instead of the normal
7245 :file:`b~`mainprog`.adb` default. Note that ``file`` denote the Ada
7246 binder generated body filename.
7247 Note that if this option is used, then linking must be done manually.
7248 It is not possible to use gnatlink in this case, since it cannot locate
7249 the binder file.
7250
7251
7252 .. index:: -r (gnatbind)
7253
7254 :switch:`-r`
7255 Generate list of ``pragma Restrictions`` that could be applied to
7256 the current unit. This is useful for code audit purposes, and also may
7257 be used to improve code generation in some cases.
7258
7259
7260 .. _Dynamic_Allocation_Control:
7261
7262 Dynamic Allocation Control
7263 ^^^^^^^^^^^^^^^^^^^^^^^^^^
7264
7265 The heap control switches -- :switch:`-H32` and :switch:`-H64` --
7266 determine whether dynamic allocation uses 32-bit or 64-bit memory.
7267 They only affect compiler-generated allocations via ``__gnat_malloc``;
7268 explicit calls to ``malloc`` and related functions from the C
7269 run-time library are unaffected.
7270
7271 :switch:`-H32`
7272 Allocate memory on 32-bit heap
7273
7274
7275 :switch:`-H64`
7276 Allocate memory on 64-bit heap. This is the default
7277 unless explicitly overridden by a ``'Size`` clause on the access type.
7278
7279 These switches are only effective on VMS platforms.
7280
7281
7282 .. _Binding_with_Non-Ada_Main_Programs:
7283
7284 Binding with Non-Ada Main Programs
7285 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7286
7287 The description so far has assumed that the main
7288 program is in Ada, and that the task of the binder is to generate a
7289 corresponding function ``main`` that invokes this Ada main
7290 program. GNAT also supports the building of executable programs where
7291 the main program is not in Ada, but some of the called routines are
7292 written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`).
7293 The following switch is used in this situation:
7294
7295
7296 .. index:: -n (gnatbind)
7297
7298 :switch:`-n`
7299 No main program. The main program is not in Ada.
7300
7301 In this case, most of the functions of the binder are still required,
7302 but instead of generating a main program, the binder generates a file
7303 containing the following callable routines:
7304
7305 .. index:: adainit
7306
7307 ``adainit``
7308 You must call this routine to initialize the Ada part of the program by
7309 calling the necessary elaboration routines. A call to ``adainit`` is
7310 required before the first call to an Ada subprogram.
7311
7312 Note that it is assumed that the basic execution environment must be setup
7313 to be appropriate for Ada execution at the point where the first Ada
7314 subprogram is called. In particular, if the Ada code will do any
7315 floating-point operations, then the FPU must be setup in an appropriate
7316 manner. For the case of the x86, for example, full precision mode is
7317 required. The procedure GNAT.Float_Control.Reset may be used to ensure
7318 that the FPU is in the right state.
7319
7320 .. index:: adafinal
7321
7322 ``adafinal``
7323 You must call this routine to perform any library-level finalization
7324 required by the Ada subprograms. A call to ``adafinal`` is required
7325 after the last call to an Ada subprogram, and before the program
7326 terminates.
7327
7328 .. index:: -n (gnatbind)
7329 .. index:: Binder, multiple input files
7330
7331 If the :switch:`-n` switch
7332 is given, more than one ALI file may appear on
7333 the command line for ``gnatbind``. The normal ``closure``
7334 calculation is performed for each of the specified units. Calculating
7335 the closure means finding out the set of units involved by tracing
7336 |with| references. The reason it is necessary to be able to
7337 specify more than one ALI file is that a given program may invoke two or
7338 more quite separate groups of Ada units.
7339
7340 The binder takes the name of its output file from the last specified ALI
7341 file, unless overridden by the use of the :switch:`-o file`.
7342
7343 .. index:: -o (gnatbind)
7344
7345 The output is an Ada unit in source form that can be compiled with GNAT.
7346 This compilation occurs automatically as part of the ``gnatlink``
7347 processing.
7348
7349 Currently the GNAT run-time requires a FPU using 80 bits mode
7350 precision. Under targets where this is not the default it is required to
7351 call GNAT.Float_Control.Reset before using floating point numbers (this
7352 include float computation, float input and output) in the Ada code. A
7353 side effect is that this could be the wrong mode for the foreign code
7354 where floating point computation could be broken after this call.
7355
7356
7357 .. _Binding_Programs_with_No_Main_Subprogram:
7358
7359 Binding Programs with No Main Subprogram
7360 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7361
7362 It is possible to have an Ada program which does not have a main
7363 subprogram. This program will call the elaboration routines of all the
7364 packages, then the finalization routines.
7365
7366 The following switch is used to bind programs organized in this manner:
7367
7368 .. index:: -z (gnatbind)
7369
7370 :switch:`-z`
7371 Normally the binder checks that the unit name given on the command line
7372 corresponds to a suitable main subprogram. When this switch is used,
7373 a list of ALI files can be given, and the execution of the program
7374 consists of elaboration of these units in an appropriate order. Note
7375 that the default wide character encoding method for standard Text_IO
7376 files is always set to Brackets if this switch is set (you can use
7377 the binder switch
7378 :switch:`-Wx` to override this default).
7379
7380
7381 .. _Command-Line_Access:
7382
7383 Command-Line Access
7384 -------------------
7385
7386 The package ``Ada.Command_Line`` provides access to the command-line
7387 arguments and program name. In order for this interface to operate
7388 correctly, the two variables
7389
7390 .. code-block:: c
7391
7392 int gnat_argc;
7393 char **gnat_argv;
7394
7395 .. index:: gnat_argv
7396 .. index:: gnat_argc
7397
7398 are declared in one of the GNAT library routines. These variables must
7399 be set from the actual ``argc`` and ``argv`` values passed to the
7400 main program. With no *n* present, ``gnatbind``
7401 generates the C main program to automatically set these variables.
7402 If the *n* switch is used, there is no automatic way to
7403 set these variables. If they are not set, the procedures in
7404 ``Ada.Command_Line`` will not be available, and any attempt to use
7405 them will raise ``Constraint_Error``. If command line access is
7406 required, your main program must set ``gnat_argc`` and
7407 ``gnat_argv`` from the ``argc`` and ``argv`` values passed to
7408 it.
7409
7410
7411 .. _Search_Paths_for_gnatbind:
7412
7413 Search Paths for ``gnatbind``
7414 -----------------------------
7415
7416 The binder takes the name of an ALI file as its argument and needs to
7417 locate source files as well as other ALI files to verify object consistency.
7418
7419 For source files, it follows exactly the same search rules as ``gcc``
7420 (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the
7421 directories searched are:
7422
7423 * The directory containing the ALI file named in the command line, unless
7424 the switch :switch:`-I-` is specified.
7425
7426 * All directories specified by :switch:`-I`
7427 switches on the ``gnatbind``
7428 command line, in the order given.
7429
7430 .. index:: ADA_PRJ_OBJECTS_FILE
7431
7432 * Each of the directories listed in the text file whose name is given
7433 by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable.
7434
7435 :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat
7436 driver when project files are used. It should not normally be set
7437 by other means.
7438
7439 .. index:: ADA_OBJECTS_PATH
7440
7441 * Each of the directories listed in the value of the
7442 :envvar:`ADA_OBJECTS_PATH` environment variable.
7443 Construct this value
7444 exactly as the :envvar:`PATH` environment variable: a list of directory
7445 names separated by colons (semicolons when working with the NT version
7446 of GNAT).
7447
7448 * The content of the :file:`ada_object_path` file which is part of the GNAT
7449 installation tree and is used to store standard libraries such as the
7450 GNAT Run-Time Library (RTL) unless the switch :switch:`-nostdlib` is
7451 specified. See :ref:`Installing_a_library`
7452
7453 .. index:: -I (gnatbind)
7454 .. index:: -aI (gnatbind)
7455 .. index:: -aO (gnatbind)
7456
7457 In the binder the switch :switch:`-I`
7458 is used to specify both source and
7459 library file paths. Use :switch:`-aI`
7460 instead if you want to specify
7461 source paths only, and :switch:`-aO`
7462 if you want to specify library paths
7463 only. This means that for the binder
7464 :switch:`-I{dir}` is equivalent to
7465 :switch:`-aI{dir}`
7466 :switch:`-aO`{dir}`.
7467 The binder generates the bind file (a C language source file) in the
7468 current working directory.
7469
7470 .. index:: Ada
7471 .. index:: System
7472 .. index:: Interfaces
7473 .. index:: GNAT
7474
7475 The packages ``Ada``, ``System``, and ``Interfaces`` and their
7476 children make up the GNAT Run-Time Library, together with the package
7477 GNAT and its children, which contain a set of useful additional
7478 library functions provided by GNAT. The sources for these units are
7479 needed by the compiler and are kept together in one directory. The ALI
7480 files and object files generated by compiling the RTL are needed by the
7481 binder and the linker and are kept together in one directory, typically
7482 different from the directory containing the sources. In a normal
7483 installation, you need not specify these directory names when compiling
7484 or binding. Either the environment variables or the built-in defaults
7485 cause these files to be found.
7486
7487 Besides simplifying access to the RTL, a major use of search paths is
7488 in compiling sources from multiple directories. This can make
7489 development environments much more flexible.
7490
7491
7492 .. _Examples_of_gnatbind_Usage:
7493
7494 Examples of ``gnatbind`` Usage
7495 ------------------------------
7496
7497 Here are some examples of ``gnatbind`` invocations:
7498
7499 ::
7500
7501 gnatbind hello
7502
7503 The main program ``Hello`` (source program in :file:`hello.adb`) is
7504 bound using the standard switch settings. The generated main program is
7505 :file:`b~hello.adb`. This is the normal, default use of the binder.
7506
7507 ::
7508
7509 gnatbind hello -o mainprog.adb
7510
7511 The main program ``Hello`` (source program in :file:`hello.adb`) is
7512 bound using the standard switch settings. The generated main program is
7513 :file:`mainprog.adb` with the associated spec in
7514 :file:`mainprog.ads`. Note that you must specify the body here not the
7515 spec. Note that if this option is used, then linking must be done manually,
7516 since gnatlink will not be able to find the generated file.
7517
7518
7519 .. _Linking_with_gnatlink:
7520
7521 Linking with ``gnatlink``
7522 =========================
7523
7524 .. index:: ! gnatlink
7525
7526 This chapter discusses ``gnatlink``, a tool that links
7527 an Ada program and builds an executable file. This utility
7528 invokes the system linker (via the ``gcc`` command)
7529 with a correct list of object files and library references.
7530 ``gnatlink`` automatically determines the list of files and
7531 references for the Ada part of a program. It uses the binder file
7532 generated by the ``gnatbind`` to determine this list.
7533
7534 .. _Running_gnatlink:
7535
7536 Running ``gnatlink``
7537 --------------------
7538
7539 The form of the ``gnatlink`` command is
7540
7541
7542 .. code-block:: sh
7543
7544 $ gnatlink [ switches ] mainprog [.ali]
7545 [ non-Ada objects ] [ linker options ]
7546
7547
7548
7549 The arguments of ``gnatlink`` (switches, main ``ALI`` file,
7550 non-Ada objects
7551 or linker options) may be in any order, provided that no non-Ada object may
7552 be mistaken for a main :file:`ALI` file.
7553 Any file name :file:`F` without the :file:`.ali`
7554 extension will be taken as the main :file:`ALI` file if a file exists
7555 whose name is the concatenation of :file:`F` and :file:`.ali`.
7556
7557 :file:`mainprog.ali` references the ALI file of the main program.
7558 The :file:`.ali` extension of this file can be omitted. From this
7559 reference, ``gnatlink`` locates the corresponding binder file
7560 :file:`b~mainprog.adb` and, using the information in this file along
7561 with the list of non-Ada objects and linker options, constructs a
7562 linker command file to create the executable.
7563
7564 The arguments other than the ``gnatlink`` switches and the main
7565 :file:`ALI` file are passed to the linker uninterpreted.
7566 They typically include the names of
7567 object files for units written in other languages than Ada and any library
7568 references required to resolve references in any of these foreign language
7569 units, or in ``Import`` pragmas in any Ada units.
7570
7571 ``linker options`` is an optional list of linker specific
7572 switches.
7573 The default linker called by gnatlink is ``gcc`` which in
7574 turn calls the appropriate system linker.
7575
7576 One useful option for the linker is :switch:`-s`: it reduces the size of the
7577 executable by removing all symbol table and relocation information from the
7578 executable.
7579
7580 Standard options for the linker such as :switch:`-lmy_lib` or
7581 :switch:`-Ldir` can be added as is.
7582 For options that are not recognized by
7583 ``gcc`` as linker options, use the ``gcc`` switches
7584 :switch:`-Xlinker` or :switch:`-Wl,`.
7585
7586 Refer to the GCC documentation for
7587 details.
7588
7589 Here is an example showing how to generate a linker map:
7590
7591 .. code-block:: sh
7592
7593 $ gnatlink my_prog -Wl,-Map,MAPFILE
7594
7595
7596 Using ``linker options`` it is possible to set the program stack and
7597 heap size.
7598 See :ref:`Setting_Stack_Size_from_gnatlink` and
7599 :ref:`Setting_Heap_Size_from_gnatlink`.
7600
7601 ``gnatlink`` determines the list of objects required by the Ada
7602 program and prepends them to the list of objects passed to the linker.
7603 ``gnatlink`` also gathers any arguments set by the use of
7604 ``pragma Linker_Options`` and adds them to the list of arguments
7605 presented to the linker.
7606
7607
7608 .. _Switches_for_gnatlink:
7609
7610 Switches for ``gnatlink``
7611 -------------------------
7612
7613 The following switches are available with the ``gnatlink`` utility:
7614
7615 .. index:: --version (gnatlink)
7616
7617 :switch:`--version`
7618 Display Copyright and version, then exit disregarding all other options.
7619
7620
7621 .. index:: --help (gnatlink)
7622
7623 :switch:`--help`
7624 If :switch:`--version` was not used, display usage, then exit disregarding
7625 all other options.
7626
7627
7628 .. index:: Command line length
7629 .. index:: -f (gnatlink)
7630
7631 :switch:`-f`
7632 On some targets, the command line length is limited, and ``gnatlink``
7633 will generate a separate file for the linker if the list of object files
7634 is too long.
7635 The :switch:`-f` switch forces this file
7636 to be generated even if
7637 the limit is not exceeded. This is useful in some cases to deal with
7638 special situations where the command line length is exceeded.
7639
7640
7641 .. index:: Debugging information, including
7642 .. index:: -g (gnatlink)
7643
7644 :switch:`-g`
7645 The option to include debugging information causes the Ada bind file (in
7646 other words, :file:`b~mainprog.adb`) to be compiled with :switch:`-g`.
7647 In addition, the binder does not delete the :file:`b~mainprog.adb`,
7648 :file:`b~mainprog.o` and :file:`b~mainprog.ali` files.
7649 Without :switch:`-g`, the binder removes these files by default.
7650
7651 .. index:: -n (gnatlink)
7652
7653 :switch:`-n`
7654 Do not compile the file generated by the binder. This may be used when
7655 a link is rerun with different options, but there is no need to recompile
7656 the binder file.
7657
7658
7659 .. index:: -v (gnatlink)
7660
7661 :switch:`-v`
7662 Verbose mode. Causes additional information to be output, including a full
7663 list of the included object files.
7664 This switch option is most useful when you want
7665 to see what set of object files are being used in the link step.
7666
7667
7668 .. index:: -v -v (gnatlink)
7669
7670 :switch:`-v -v`
7671 Very verbose mode. Requests that the compiler operate in verbose mode when
7672 it compiles the binder file, and that the system linker run in verbose mode.
7673
7674
7675 .. index:: -o (gnatlink)
7676
7677 :switch:`-o {exec-name}`
7678 ``exec-name`` specifies an alternate name for the generated
7679 executable program. If this switch is omitted, the executable has the same
7680 name as the main unit. For example, ``gnatlink try.ali`` creates
7681 an executable called :file:`try`.
7682
7683
7684 .. index:: -B (gnatlink)
7685
7686 :switch:`-B{dir}`
7687 Load compiler executables (for example, ``gnat1``, the Ada compiler)
7688 from ``dir`` instead of the default location. Only use this switch
7689 when multiple versions of the GNAT compiler are available.
7690 See the ``Directory Options`` section in :title:`The_GNU_Compiler_Collection`
7691 for further details. You would normally use the :switch:`-b` or
7692 :switch:`-V` switch instead.
7693
7694
7695 .. index:: -M (gnatlink)
7696
7697 :switch:`-M`
7698 When linking an executable, create a map file. The name of the map file
7699 has the same name as the executable with extension ".map".
7700
7701
7702 .. index:: -M= (gnatlink)
7703
7704 :switch:`-M={mapfile}`
7705 When linking an executable, create a map file. The name of the map file is
7706 ``mapfile``.
7707
7708
7709 .. index:: --GCC=compiler_name (gnatlink)
7710
7711 :switch:`--GCC={compiler_name}`
7712 Program used for compiling the binder file. The default is
7713 ``gcc``. You need to use quotes around ``compiler_name`` if
7714 ``compiler_name`` contains spaces or other separator characters.
7715 As an example ``--GCC="foo -x -y"`` will instruct ``gnatlink`` to
7716 use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always
7717 inserted after your command name. Thus in the above example the compiler
7718 command that will be used by ``gnatlink`` will be ``foo -c -x -y``.
7719 A limitation of this syntax is that the name and path name of the executable
7720 itself must not include any embedded spaces. If the compiler executable is
7721 different from the default one (gcc or <prefix>-gcc), then the back end
7722 switches in the ALI file are not used to compile the binder generated source.
7723 For example, this is the case with ``--GCC="foo -x -y"``. But the back end
7724 switches will be used for ``--GCC="gcc -gnatv"``. If several
7725 ``--GCC=compiler_name`` are used, only the last ``compiler_name``
7726 is taken into account. However, all the additional switches are also taken
7727 into account. Thus,
7728 ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to
7729 ``--GCC="bar -x -y -z -t"``.
7730
7731
7732 .. index:: --LINK= (gnatlink)
7733
7734 :switch:`--LINK={name}`
7735 ``name`` is the name of the linker to be invoked. This is especially
7736 useful in mixed language programs since languages such as C++ require
7737 their own linker to be used. When this switch is omitted, the default
7738 name for the linker is ``gcc``. When this switch is used, the
7739 specified linker is called instead of ``gcc`` with exactly the same
7740 parameters that would have been passed to ``gcc`` so if the desired
7741 linker requires different parameters it is necessary to use a wrapper
7742 script that massages the parameters before invoking the real linker. It
7743 may be useful to control the exact invocation by using the verbose
7744 switch.
7745
7746
7747 .. _Using_the_GNU_make_Utility:
7748
7749 Using the GNU ``make`` Utility
7750 ==============================
7751
7752 .. index:: make (GNU), GNU make
7753
7754 This chapter offers some examples of makefiles that solve specific
7755 problems. It does not explain how to write a makefile, nor does it try to replace the
7756 ``gnatmake`` utility (:ref:`The_GNAT_Make_Program_gnatmake`).
7757
7758 All the examples in this section are specific to the GNU version of
7759 make. Although ``make`` is a standard utility, and the basic language
7760 is the same, these examples use some advanced features found only in
7761 ``GNU make``.
7762
7763 .. _Using_gnatmake_in_a_Makefile:
7764
7765 Using gnatmake in a Makefile
7766 ----------------------------
7767
7768 .. index makefile (GNU make)
7769
7770 Complex project organizations can be handled in a very powerful way by
7771 using GNU make combined with gnatmake. For instance, here is a Makefile
7772 which allows you to build each subsystem of a big project into a separate
7773 shared library. Such a makefile allows you to significantly reduce the link
7774 time of very big applications while maintaining full coherence at
7775 each step of the build process.
7776
7777 The list of dependencies are handled automatically by
7778 ``gnatmake``. The Makefile is simply used to call gnatmake in each of
7779 the appropriate directories.
7780
7781 Note that you should also read the example on how to automatically
7782 create the list of directories
7783 (:ref:`Automatically_Creating_a_List_of_Directories`)
7784 which might help you in case your project has a lot of subdirectories.
7785
7786
7787 .. code-block:: makefile
7788
7789 ## This Makefile is intended to be used with the following directory
7790 ## configuration:
7791 ## - The sources are split into a series of csc (computer software components)
7792 ## Each of these csc is put in its own directory.
7793 ## Their name are referenced by the directory names.
7794 ## They will be compiled into shared library (although this would also work
7795 ## with static libraries)
7796 ## - The main program (and possibly other packages that do not belong to any
7797 ## csc) is put in the top level directory (where the Makefile is).
7798 ## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
7799 ## \\_ second_csc (sources) __ lib (will contain the library)
7800 ## \\_ ...
7801 ## Although this Makefile is build for shared library, it is easy to modify
7802 ## to build partial link objects instead (modify the lines with -shared and
7803 ## gnatlink below)
7804 ##
7805 ## With this makefile, you can change any file in the system or add any new
7806 ## file, and everything will be recompiled correctly (only the relevant shared
7807 ## objects will be recompiled, and the main program will be re-linked).
7808
7809 # The list of computer software component for your project. This might be
7810 # generated automatically.
7811 CSC_LIST=aa bb cc
7812
7813 # Name of the main program (no extension)
7814 MAIN=main
7815
7816 # If we need to build objects with -fPIC, uncomment the following line
7817 #NEED_FPIC=-fPIC
7818
7819 # The following variable should give the directory containing libgnat.so
7820 # You can get this directory through 'gnatls -v'. This is usually the last
7821 # directory in the Object_Path.
7822 GLIB=...
7823
7824 # The directories for the libraries
7825 # (This macro expands the list of CSC to the list of shared libraries, you
7826 # could simply use the expanded form:
7827 # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
7828 LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so}
7829
7830 ${MAIN}: objects ${LIB_DIR}
7831 gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared
7832 gnatlink ${MAIN} ${CSC_LIST:%=-l%}
7833
7834 objects::
7835 # recompile the sources
7836 gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%}
7837
7838 # Note: In a future version of GNAT, the following commands will be simplified
7839 # by a new tool, gnatmlib
7840 ${LIB_DIR}:
7841 mkdir -p ${dir $@ }
7842 cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat
7843 cd ${dir $@ } && cp -f ../*.ali .
7844
7845 # The dependencies for the modules
7846 # Note that we have to force the expansion of *.o, since in some cases
7847 # make won't be able to do it itself.
7848 aa/lib/libaa.so: ${wildcard aa/*.o}
7849 bb/lib/libbb.so: ${wildcard bb/*.o}
7850 cc/lib/libcc.so: ${wildcard cc/*.o}
7851
7852 # Make sure all of the shared libraries are in the path before starting the
7853 # program
7854 run::
7855 LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN}
7856
7857 clean::
7858 ${RM} -rf ${CSC_LIST:%=%/lib}
7859 ${RM} ${CSC_LIST:%=%/*.ali}
7860 ${RM} ${CSC_LIST:%=%/*.o}
7861 ${RM} *.o *.ali ${MAIN}
7862
7863
7864 .. _Automatically_Creating_a_List_of_Directories:
7865
7866 Automatically Creating a List of Directories
7867 --------------------------------------------
7868
7869 In most makefiles, you will have to specify a list of directories, and
7870 store it in a variable. For small projects, it is often easier to
7871 specify each of them by hand, since you then have full control over what
7872 is the proper order for these directories, which ones should be
7873 included.
7874
7875 However, in larger projects, which might involve hundreds of
7876 subdirectories, it might be more convenient to generate this list
7877 automatically.
7878
7879 The example below presents two methods. The first one, although less
7880 general, gives you more control over the list. It involves wildcard
7881 characters, that are automatically expanded by ``make``. Its
7882 shortcoming is that you need to explicitly specify some of the
7883 organization of your project, such as for instance the directory tree
7884 depth, whether some directories are found in a separate tree, etc.
7885
7886 The second method is the most general one. It requires an external
7887 program, called ``find``, which is standard on all Unix systems. All
7888 the directories found under a given root directory will be added to the
7889 list.
7890
7891 .. code-block:: makefile
7892
7893 # The examples below are based on the following directory hierarchy:
7894 # All the directories can contain any number of files
7895 # ROOT_DIRECTORY -> a -> aa -> aaa
7896 # -> ab
7897 # -> ac
7898 # -> b -> ba -> baa
7899 # -> bb
7900 # -> bc
7901 # This Makefile creates a variable called DIRS, that can be reused any time
7902 # you need this list (see the other examples in this section)
7903
7904 # The root of your project's directory hierarchy
7905 ROOT_DIRECTORY=.
7906
7907 ####
7908 # First method: specify explicitly the list of directories
7909 # This allows you to specify any subset of all the directories you need.
7910 ####
7911
7912 DIRS := a/aa/ a/ab/ b/ba/
7913
7914 ####
7915 # Second method: use wildcards
7916 # Note that the argument(s) to wildcard below should end with a '/'.
7917 # Since wildcards also return file names, we have to filter them out
7918 # to avoid duplicate directory names.
7919 # We thus use make's ``dir`` and ``sort`` functions.
7920 # It sets DIRs to the following value (note that the directories aaa and baa
7921 # are not given, unless you change the arguments to wildcard).
7922 # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
7923 ####
7924
7925 DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/
7926 ${ROOT_DIRECTORY}/*/*/}}}
7927
7928 ####
7929 # Third method: use an external program
7930 # This command is much faster if run on local disks, avoiding NFS slowdowns.
7931 # This is the most complete command: it sets DIRs to the following value:
7932 # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
7933 ####
7934
7935 DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print}
7936
7937
7938
7939 .. _Generating_the_Command_Line_Switches:
7940
7941 Generating the Command Line Switches
7942 ------------------------------------
7943
7944 Once you have created the list of directories as explained in the
7945 previous section (:ref:`Automatically_Creating_a_List_of_Directories`),
7946 you can easily generate the command line arguments to pass to gnatmake.
7947
7948 For the sake of completeness, this example assumes that the source path
7949 is not the same as the object path, and that you have two separate lists
7950 of directories.
7951
7952 .. code-block:: makefile
7953
7954 # see "Automatically creating a list of directories" to create
7955 # these variables
7956 SOURCE_DIRS=
7957 OBJECT_DIRS=
7958
7959 GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}}
7960 GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}}
7961
7962 all:
7963 gnatmake ${GNATMAKE_SWITCHES} main_unit
7964
7965
7966 .. _Overcoming_Command_Line_Length_Limits:
7967
7968 Overcoming Command Line Length Limits
7969 -------------------------------------
7970
7971 One problem that might be encountered on big projects is that many
7972 operating systems limit the length of the command line. It is thus hard to give
7973 gnatmake the list of source and object directories.
7974
7975 This example shows how you can set up environment variables, which will
7976 make ``gnatmake`` behave exactly as if the directories had been
7977 specified on the command line, but have a much higher length limit (or
7978 even none on most systems).
7979
7980 It assumes that you have created a list of directories in your Makefile,
7981 using one of the methods presented in
7982 :ref:`Automatically_Creating_a_List_of_Directories`.
7983 For the sake of completeness, we assume that the object
7984 path (where the ALI files are found) is different from the sources patch.
7985
7986 Note a small trick in the Makefile below: for efficiency reasons, we
7987 create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
7988 expanded immediately by ``make``. This way we overcome the standard
7989 make behavior which is to expand the variables only when they are
7990 actually used.
7991
7992 On Windows, if you are using the standard Windows command shell, you must
7993 replace colons with semicolons in the assignments to these variables.
7994
7995 .. code-block:: makefile
7996
7997 # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH.
7998 # This is the same thing as putting the -I arguments on the command line.
7999 # (the equivalent of using -aI on the command line would be to define
8000 # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH).
8001 # You can of course have different values for these variables.
8002 #
8003 # Note also that we need to keep the previous values of these variables, since
8004 # they might have been set before running 'make' to specify where the GNAT
8005 # library is installed.
8006
8007 # see "Automatically creating a list of directories" to create these
8008 # variables
8009 SOURCE_DIRS=
8010 OBJECT_DIRS=
8011
8012 empty:=
8013 space:=${empty} ${empty}
8014 SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}}
8015 OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}}
8016 ADA_INCLUDE_PATH += ${SOURCE_LIST}
8017 ADA_OBJECTS_PATH += ${OBJECT_LIST}
8018 export ADA_INCLUDE_PATH
8019 export ADA_OBJECTS_PATH
8020
8021 all:
8022 gnatmake main_unit
8023
8024 .. _GNATLLVM:
8025
8026 GNAT with the LLVM Back End
8027 ===========================
8028
8029 This section outlines the usage of the GNAT compiler with the LLVM
8030 back end and highlights its key limitations. Certain GNAT versions,
8031 referred to as GNAT LLVM, include an alternative LLVM back end
8032 alongside the GCC back end, providing access to utilities that operate
8033 at the LLVM Intermediate Representation (IR) level. This also enhances
8034 safety by facilitating dissimilar redundancy through diverse code
8035 generation techniques, allowing for the creation of two distinct
8036 binaries from the same source code.
8037
8038 Although both GNAT LLVM and the GCC-based GNAT follow most ABI rules,
8039 there are some cases where there you may encounter an incompatibility
8040 between the two compilers. One such case for the 64-bit Intel X86 is
8041 a difference in parameter passing when a structure that consists of 64
8042 bits is passed. The native LLVM handling (and hence that of GNAT LLVM)
8043 and ``clang`` disagree in this case. GCC follows ``clang``. The formal
8044 ABI agrees with LLVM.
8045
8046 In any case, we don't recommend you link code compiled with GNAT LLVM
8047 to code compiled by the GCC version of GNAT. This is a specific case
8048 of the general rule that you should compile all your Ada code with the
8049 same version of GNAT. Both ``gnatmake`` and ``gprbuild`` ensure this
8050 is done.
8051
8052 You may, however, run into this incompatibility if you pass such a
8053 record between C and Ada. In general, we recommend keeping the data
8054 passed between C and Ada as simple as practical.
8055
8056 GNAT LLVM currently provides limited support for debugging data. It
8057 provides full line number information for declarations and statements,
8058 but not sufficient debugging data to display all Ada data
8059 structures. GNAT LLVM outputs complete debugging data only for types
8060 with a direct equivalent in C, namely records without discriminants
8061 and constrained arrays whose dimensions are known at compile time. You
8062 will not be able to use ``gdb`` print commands to look at objects not
8063 of those types or to display components of those types. You can use
8064 low-level ``gdb`` commands that display memory to view such data
8065 provided you know how they're laid out. Debugging information may
8066 also be limited for bitfields (fields whose size and position
8067 aren't on byte boundaries)
8068
8069 In addition, debugging information may be confusing if you have
8070 ``out`` parameters to subprograms. If you have a procedure with only
8071 one ``out`` parameter, GNAT LLVM converts that to a function returning
8072 an object of that type. If you have multiple ``out`` parameters or
8073 have a function that also has an ``out`` parameter, GNAT LLVM converts
8074 that subprogram into a function that returns a record where each field
8075 is either an ``out`` parameter or the function return value, if any.
8076 The debug information reflects these transformations and not the original
8077 Ada source code.
8078
8079 GNAT LLVM doesn't fully implement the :switch:`-fcheck-stack` switch.
8080 When you specify it, the code generated by GNAT LLVM tests for allocating
8081 overly-large items on the stack, but not all cases of stack overflow. For
8082 example, if you have a very deep recursion where each call only uses a
8083 small amount of stack and the total stack depth exceeds the amount of
8084 available stack, the program will be terminated by a signal instead of
8085 raising an Ada exception.
8086
8087 GNAT LLVM doesn't support the ``Scalar_Storage_Order`` pragma except when
8088 it's used to confirm the chosen storage order. This is because this facility
8089 is provided by GCC but not by LLVM.
8090
8091 GNAT LLVM doesn't support Convention C++, which provides so-called
8092 'name mangling' by encoding parameter and return datatypes into a
8093 function name.
8094
8095 .. only:: PRO
8096
8097 Unlike the GCC versions of GNAT, GNAT LLVM doesn't include any
8098 Ada libraries. You can obtain source packages from GNATtracker and
8099 build them with the compiler configuration appropriate for your
8100 project. AdaCore internally builds and tests the GNAT Components
8101 Collection, XML/Ada, and AUnit libraries to ensure compatibility
8102 with GNAT LLVM, but not all options of those libraries are
8103 currently supported with all targets of GNAT LLVM. If you need to
8104 use any of these libraries, please open a support ticket.
8105
8106 We provide two options that you can use to build code with GNAT LLVM:
8107
8108 * GNAT LLVM includes a version of ``gnatmake`` called
8109 ``llvm-gnatmake``, which is equivalent to ``gnatmake`` and has the
8110 same switches, except that it uses GNAT LLVM instead of the GCC
8111 version of GNAT.
8112
8113 * ``gprbuild`` can detect and use GNAT LLVM when it is installed.
8114
8115 ``gprbuild`` uses the first applicable compiler on the executable
8116 search path, including GNAT LLVM. An easy way to build with GNAT
8117 LLVM is to make it available on the operating system's search path
8118 before any other Ada compiler (such as the GCC version of GNAT). To
8119 avoid accidentally using a different compiler than the one you want
8120 to use, we recommend generating an explicit toolchain configuration
8121 file with ``gprconfig`` and using it with ``gprbuild``; see the
8122 *GPRbuild and GPR Companion Tools User's Guide* for details. You
8123 can determine from the first line of the :file:`.ali` file
8124 which version of GNAT built that file because it contains either
8125 :code:`GNAT` or :code:`GNAT-LLVM`.
8126
8127 .. only:: PRO
8128
8129 If your project uses one of the libraries packaged with the GCC
8130 version of GNAT, it is important that you use the GPR tools from
8131 the GNAT LLVM package when building with GNAT LLVM. Otherwise,
8132 ``gprbuild`` would try to use the precompiled libraries shipped with
8133 the GCC version of GNAT, mixing those objects with code generated
8134 by GNAT LLVM, which is not supported.
8135
8136 GNAT LLVM understands the same target triplets as the GCC version of
8137 GNAT.
8138
8139 .. only:: PRO
8140
8141 It provides the same runtimes with the exception that light runtimes
8142 are not currently included with the native compilers.