26. Creating Sample Bodies with gnatstub
gnatstub
creates body stubs, that is, empty but compilable bodies
for library unit declarations.
To create a body stub, gnatstub
invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
information needed to compile the input source. To provide this information,
you may specify as a tool parameter the project file the input source belongs to
(or you may call gnatstub
through the gnat
driver (see 12.2 The GNAT Driver and Project Files). Another possibility is to specify the source search
path and needed configuration files in `-cargs' section of gnatstub
call, see the description of the gnatstub
switches below.
If the gnatstub
argument source contains preprocessing directives
then the needed options should be provided to run preprocessor as a part of
the gnatstub
call, and the generated body stub will correspond to
the preprocessed source.
By default, all the program unit body stubs generated by gnatstub
raise the predefined Program_Error
exception, which will catch
accidental calls of generated stubs. This behavior can be changed with
option `--no-exception' (see below).
26.1 Running gnatstub
gnatstub
has a command-line interface of the form:
| $ gnatstub [switches] filename [directory] [-cargs gcc_switches]
|
where
- filename
- is the name of the source file that contains a library unit declaration
for which a body must be created. The file name may contain the path
information.
The file name does not have to follow the GNAT file name conventions. If the
name
does not follow GNAT file naming conventions, the name of the body file must
be provided
explicitly as the value of the `-obody-name' option.
If the file name follows the GNAT file naming
conventions and the name of the body file is not provided,
gnatstub
creates the name
of the body file from the argument file name by replacing the `.ads'
suffix
with the `.adb' suffix.
- directory
- indicates the directory in which the body stub is to be placed (the default
is the
current directory)
- `gcc_switches' is a list of switches for
gcc
. They will be passed on to all compiler invocations made by
gnatstub
to generate the ASIS trees. Here you can provide
`-I' switches to form the source search path,
use the `-gnatec' switch to set the configuration file,
use the `-gnat05' switch if sources should be compiled in
Ada 2005 mode etc.
- switches
- is an optional sequence of switches as described in the next section
26.2 Switches for gnatstub
- `--version'
-
Display Copyright and version, then exit disregarding all other options.
- `--help'
-
Display usage, then exit disregarding all other options.
- `-P file'
-
Indicates the name of the project file that describes the set of sources
to be processed.
- `-Xname=value'
-
Indicates that external variable name in the argument project
has the value value. Has no effect if no project is specified as
tool argument.
- `-f'
-
If the destination directory already contains a file with the name of the
body file
for the argument spec file, replace it with the generated body stub.
- `-hs'
-
Put the comment header (i.e., all the comments preceding the
compilation unit) from the source of the library unit declaration
into the body stub.
- `-hg'
-
Put a sample comment header into the body stub.
- `--header-file=filename'
-
Use the content of the file as the comment header for a generated body stub.
- `-IDIR'
-
- `-I-'
-
These switches have the same meaning as in calls to
gcc
.
They define the source search path in the call to
gcc
issued
by gnatstub
to compile an argument source file.
- `-gnatecPATH'
-
This switch has the same meaning as in calls to
gcc
.
It defines the additional configuration file to be passed to the call to
gcc
issued
by gnatstub
to compile an argument source file.
- `-gnatyMn'
-
(n is a non-negative integer). Set the maximum line length that is
allowed in a source file. The default is 79. The maximum value that can be
specified is 32767. Note that in the special case of configuration
pragma files, the maximum is always 32767 regardless of whether or
not this switch appears.
- `-gnatyn'
-
(n is a non-negative integer from 1 to 9). Set the indentation level in
the generated body sample to n.
The default indentation is 3.
- `-gnatyo'
-
Order local bodies alphabetically. (By default local bodies are ordered
in the same way as the corresponding local specs in the argument spec file.)
- `-in'
-
Same as `-gnatyn'
- `-k'
-
Do not remove the tree file (i.e., the snapshot of the compiler internal
structures used by
gnatstub
) after creating the body stub.
- `-ln'
-
Same as `-gnatyMn'
- `--no-exception'
-
Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs.
This is not always possible for function stubs.
- `--no-local-header'
-
Do not place local comment header with unit name before body stub for a
unit.
- `-o body-name'
-
Body file name. This should be set if the argument file name does not
follow
the GNAT file naming
conventions. If this switch is omitted the default name for the body will be
obtained
from the argument file name according to the GNAT file naming conventions.
- `-We'
-
Specify the wide character encoding method for the output body file.
e is one of the following:
- h
Hex encoding
- u
Upper half encoding
- s
Shift/JIS encoding
- e
EUC encoding
- 8
UTF-8 encoding
- b
Brackets encoding (default value)
- `-q'
-
Quiet mode: do not generate a confirmation when a body is
successfully created, and do not generate a message when a body is not
required for an
argument unit.
- `-r'
-
Reuse the tree file (if it exists) instead of creating it. Instead of
creating the tree file for the library unit declaration,
gnatstub
tries to find it in the current directory and use it for creating
a body. If the tree file is not found, no body is created. This option
also implies `-k', whether or not
the latter is set explicitly.
- `-t'
-
Overwrite the existing tree file. If the current directory already
contains the file which, according to the GNAT file naming rules should
be considered as a tree file for the argument source file,
gnatstub
will refuse to create the tree file needed to create a sample body
unless this option is set.
- `-v'
-
Verbose mode: generate version information.
This document was generated
by GNAT Mailserver on April, 17 2014
using texi2html