25. Creating Sample Bodies Using gnatstub

gnatstub creates body stubs, that is, empty but compilable bodies for library unit declarations.

Note: to invoke gnatstub with a project file, use the gnat driver (see 12.2 The GNAT Driver and Project Files).

To create a body stub, gnatstub has to compile the library unit declaration. Therefore, bodies can be created only for legal library units. Moreover, if a library unit depends semantically upon units located outside the current directory, you have to provide the source search path when calling gnatstub, see the description of gnatstub switches below.

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

25.1 Running gnatstub
25.2 Switches for gnatstub

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

25.2 Switches for gnatstub

`-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 in the body stub to n; 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.

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