17. Creating Sample Bodies Using gnatstub

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

gnatstub is an ASIS-based tool, but it creates a needed tree file itself, so it can be considered as a usual command-line utility program when using with GNAT.

To create a body sampler, 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 not only in the current directory, you have to provide a source search path when calling gnatstub, see the description of gnatstub switches below.

17.1 Running gnatstub
17.2 Switches for gnatstub

17.1 Running gnatstub

gnatstub has the command-line interface of the form

$ gnatstub [switches] filename [directory]

where

filename

is the name of a source file containing a library unit declaration to create a body for. This name should follow the GNAT file name conventions. No crunching is allowed for this file name. The file name may contain the path information.

directory

indicates the directory to place a sample body (default is the current directory)

switches

is an optional sequence of switches as described in the next section

17.2 Switches for gnatstub

-f

Replace an existing body file (if any) with a body sample. If the destination directory already contains a file which name has a form of the body file for the argument spec file, gnatstub replaces it with the body sample if -f switch is set or leaves it intact otherwise.

-hs

Put in body sample the comment header from the source of the library unit declaration ("comment header" is all the comments preceding the compilation unit).

-hg

Put in body sample a sample comment header

-IDIR

-I-

These switches have just the same meaning as in calls to gnatgcc or gnatmake. They are used to define the source search path in the call to gnatgcc issued by gnatstub to compile an argument source file to create a tree file.

-in

(n is a decimal natural number). Sets the indentation level in the generated body sample to n, '-i0' means "no indentation", the default indentation is 3.

-k

Do not remove the tree file: as default, after creating the body sampler gnatstub removes from the current directory the tree file created for the argument source file. -k prevents deleting the tree file.

-ln

(n is a decimal positive number) Sets maximum line length in a body sample to n, the default line length is 78.

-q

Quiet mode: gnatstub does not generate a confirmation when a body is successfully created or a message when a body is not required for an argument unit.

-r

Reuse the tree file (if any) 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 to use it for creating a body. If the tree file is not found, no body is created. -r also implies -k, whether or not -k is set explicitly.

-t

Overwrite the existing tree file: if the current directory already contains the file which, according to the GNAT file name 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 body sampler, unless -t option is set

-v

Verbose mode: gnatstub generates version information.