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