Contents.
---------

What is gnatstub?
How it works?
The content and the format of a body sample
gnatstub options
Submitting bug reports


What is gnatstub?
-----------------
gnatstub is an Ada library unit body sample generator. It takes a source
file containing the source of an Ada library unit declaration and
generates the sample body for this unit in another source file. Sample
body is a kind of "minimal", but compilable body for a given unit
declaration.

gnatstub is free software. It was originally developed by Alexei Kuchumov
as a part of collaboration between Software Engineering Laboratory of the
Swiss Federal Institute of Technology in Lausanne, Switzerland, in
cooperation with the Scientific Research Computer Center of Moscow State
University (SRCC MSU), Russia. This work was supported by a grant from the
Swiss National Science Foundation, no 7SUPJ048247, funding a project
entitled "Development of ASIS for GNAT with industry quality".

Now gnatstub is maintained by Ada Core Technologies, Inc
(http://www.gnat.com).


How it works?
-------------
gnatstub is an ASIS application developed on top of the ASIS
implementation for GNAT (ASIS 2.0.P). The important thing to know about
gnatstub is that to create a body, gnatstub first compiles the spec to
create in your current directory the tree output file (or, simply, a tree
file). After creating a body gnatstub deletes this tree file (the tree file
may be kept by setting the corresponding option. Therefore, if you have some
other ASIS-based tools built on top of ASIS-for-GNAT, working on the tree
files located in your current directory, be aware of possible changes in the
set of tree files as a result of using gnatstub.

If gnatstub argument is an illegal Ada unit, no body can be created for
it.

For more details concerning tree files, see ASIS-for-GNAT User's Guide.


The content and the format of a body sample
-------------------------------------------

When creating a body sampler, gnatstub orders all the local body samples
alphabetically. Full type declarations generated as completions of incomplete
type declarations from a private part of a package or generic package
specification, are not ordered and they are placed in the very beginning of
the corresponding body sampler.

If an argument library unit contains a local package or generic package
which in turn does not contain any declaration requiring completion, then the
local body sample for this local package or generic package is not created.

Each body sample is printed in the body file with the indentation level
corresponding to the nesting level of this body in the enclosing Ada code.
The number of spaces used to represent one indentation level is set by -n
option, the default indentation is 3.

When generating a body sampler, gnatstub is trying to keep all the lines of
the generated source under the maximum line length, which can be set by -l
option (the default maximum line length is 78).


gnatstub options
----------------
gnatstub has the command-line interface of the form

   gnatstub [options] filename [directory]

'filename' is the 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 (that is the source to create a body for may be located
not only in the current directory).

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

gnatstub options:

-f

  Replace an existing body file (if any) with a body sample. If
  destination directory contains a file which should be considered as the
  body for 'filename' according to the GNAT file name conventions,
  gnatstub treats this file as a body for 'filename', and it does not
  create a sample body if '-f' option is not set;

-hs

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

-hg

  Put in body sample a sample comment header

-Idir -I-

  These options have just the same meaning as in calls to gcc or gnatmake.
  They are used to define the source search path in the call to gcc issued
  by gnatstub to create the tree file. Note, that to create a body,
  gnatstub needs a legal Ada unit, therefore if 'filename' depends on some
  unit located in another directory, '-I' should be used to provide the
  path to this unit.

-in

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

-k

  Do not remove the tree file: as default, gnatstub removes from the
  current directory the tree file created for 'filename' after creating
  the body sampler. '-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 'filename' gnatstub tries to find it in the current
  directory and to use it for creating a body. If there is no tree file
  for 'filename' in the current directory, no body is created. Note, that
  the body will be created for those version of the compilation unit,
  which is represented by the tree, but not by the source file. Note also,
  that '-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 'filename', 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.

Submitting bug reports
----------------------
Send all the bug reports, as well as any comments concerning the gnatstub
functionality and options, which are very welcomed, to asis-report@gnat.com