| 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 |