GNAT GPL User's Guide: Creating Sample Bodies with gnatstub

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 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` |  |
> 26.2 Switches for `gnatstub` |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

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

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by GNAT Mailserver on April, 17 2014 using texi2html