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