adabrowse - Generate fully cross-referenced HTML rendering of Ada 95 specs
[options] -f file
produces a fully cross-referenced HTML rendering of Ada 95
specs (no bodies) similar to what javadoc does for Java sources.
is a command-line utility; it has no graphical user
is highly configurable through command-line options, style
sheets, and configuration files.
completely takes apart the source code and produces a HTML
- All context clauses
- Unit header
- If the unit is a package:
- All exceptions (including renames)
- All constants
- All variables
- A type index containing all types and their primitive
operations (the latter only for (tagged) record types, private types, and
types derived from those). The primitive operations list is fully
cross-referenced and ordered by newly defined, overridden, and inherited
- Any other items
There are two ways to use adabrowse
- Call adabrowse for your spec: adabrowse -f
file (and any other options as needed, in particular -I if
the file is not in the current directory or depends on other units whose
sources are not in the current directory!) If no tree file for the given
unit exists, adabrowse will try to generate one.
- Generate the tree files for the specs you want to process
by calling gnatgcc -c -gnatc -gnatt file (with the
appropriate -I options, if needed.)
- Call adabrowse for these specs: adabrowse -f
file (and any other options, as needed [look in particular at
generates HTML files by default in the current directory.
doesn't care whether the tree files have been produced from
specs or bodies: since the tree file of a body always also contains the
information on the spec, it can work with either.
- -h, -?, -help, --help
- Writes a comprehensive help text.
- -a, -all, --all
- Generate HTML not only for the unit given in the -f option,
but also for all application units on which it depends semantically
(transitive closure of "with"es and parent units).
- Note that this option processes only the application units
in the transitive closure even if the "-g" option is also given;
it does not process any "with"ed standard library unit. This
also means that if the unit given is a standard library unit, the
"-all" option has no effect. This behavior is intentional:
you'll normally generate HTML for the standard library once by processing
all standard library units explicitly, and you don't want to re-generate
HTML for these units each time one of your application unit
"with"es a standard library unit.
- -c file
- Defines a configuration file for the HTML generator.
Multiple -c options may be given; the files are processed in the
given order and may overwrite earlier config settings.
- -f file
- Gives the filename (*.ads) of the spec to process. This
filename may contain a path! See below for more comments. Only one
-f option may be given.
- If set, adabrowse also generates cross-references to
items from library units in the standard and run-time packages, except for
items from the implict package "Standard". Note: This can also
be set by a configuration file key "Refs_To_Standard". The
latter definition wins.
- -G output_formats...
- Specify the output formats adabrowse shall generate.
The -G option must be followed by one or more output format names,
given as separate arguments. Recognized output format names are
html and xml (case insensitive).
- -i [file]
- If set, adabrowse will generate a package index if
it runs in "file input mode" (see below) or the -all
option is set and the output does not go to stdout.
If a filename is given, the index is written to that file (or to stdout, if
the filename is "-").
- -is [file]
- Same as -i, but generates an index using indentation for
- Make adabrowse generate cross-references in HTML
output using only the line number. This is what earlier versions of
adabrowse (up to and including V2.13) always did. As of V3.0,
cross-references are constructed taking into account both line and column
number of an item. You should use this option only if you have HTML
documentation generated by earlier adabrowse versions and somehow
cannot re-generate that documentation. However, the recommended usage is
never to use this option and to regenerate possibly already existing HTML
Note that HTML generated with -l is not compatible with HTML
generated without -l! Also, HTML generated by adabrowse 3.0
and beyond is compatible with HTML generated by adabrowse 2.13 and
earlier only if the -l option is given.
Usage of this option generates a warning message on stderr.
- -o [file]
- Define the output file name. If not set, the output goes to
a file with the name of the input and suffix .html. If file
specifies a directory (i.e., ends in a "\" on Windows or a
"/" on Unix), all generated HTML files will be put into that
directory. If the filename is "-", output is written to stdout.
Only one -o option may be given.
A dash as the filename ("-") is allowed only if there is exactly
one output format specified. If there are multiple output formats
specified (e.g. both XML and HTML), output is not allowed to go to stdout.
- -p [file]
- As -i, but generates a subprogram index over all
- -private, --private
- If given, adabrowse will also process the private
parts of packages and task or protected declarations. (By default, it
doesn't do so but replaces the private parts by a comment saying
- Quiet mode: do not issue warning or info messages. Synonym
- -s URL
- Defines the URL to the style sheet the generated HTML file
shall use. This URL should be relative to the final place where you will
put the HTML files! Note that a -s option can be overwritten by a
later -c option, if the configuration file defines the key
- -t [file]
- As -i, but generates a global type index over all
- -version, --version
- Print version information of adabrowse to stderr.
- Sets the warning level of adabrowse. i may be
one of the following:
- 0, or e
- print only error messages.
- 1, or w
- print warnings and errors.
- 2, or i, or a
- print all messages.
- If set, adabrowse never overwrites existing HTML
files. (May be useful in conjunction with the -a option.)
- -X name=value
- Define an environment variable name with value
value. The value supersedes any possibly already existing
definition of name in the system's environment for this call to
adabrowse. The new definition affects any configuration file
processed subsequently and also the project file (if any). The name
must not contain white space; if value contains white space, quote
the whole definition as in -X"user=John Doe". There may or may
not be white space between the -X and the variable definition.
- -I directory
- Define source paths for ASIS. Same semantics as for GNAT.
Multiple -I options may be given.
- -T directory
- Define paths for ASIS to search for tree files (*.adt).
Multiple -T options may be given.
Note that if you give a filename to the -i option that starts with
the letter "s", you must have a white space between the option
and the filename, otherwise it will be recognized as a -is option.
Also, if the filename starts with "-", there mustn't be any
whitespace between the option and the filename, for if there is,
adabrowse will assume the filename to be the next option and handle
it as such (options all start with "-"), and not as a filename.
The same caveat also applies to the -p option, if you want the
subprogram index to go to a file named "rivate": there must be a
blank, otherwise, the whole thing will be recognized as the
-private option. (Admittedly this is a rather pathological case,
but it's mentioned here for completeness.)
option has three different formats:
- If the filename is "-" or "@-",
adabrowse reads the unit specs of the units to process from stdin,
one unit per line, until EOF is encountered. Empty lines are skipped. (If
you try this interactively, you'll have to signal EOF yourself. Otherwise,
this may be useful if the input comes from a pipe, like in "ls -1
*.ads | adabrowse -f- ...")
- If the filename starts with "@", adabrowse
doesn't consider it a unit spec, but as the name of a text file from which
to read the unit names, one unit per line. Empty lines in the file are
- If neither applies, adabrowse uses the given
filename as the unit spec.
The first two cases are called the "file input mode" of
. The file may contain empty lines and comments (starting with
the first "#" on a line and extending up to the end of the line),
which are ignored. Note that contrary to configuration files, string handling
for finding comment starts is not done, and line continuations also are not
In all three cases, a unit spec is a filename that may contain a path; a
possible suffix is ignored. Note that a unit spec is a file name; in other
words, you give test-gen
, or test-gen.ads
, and not
. The reason is simply that for most shell scripting languages,
it is easier to work with filenames than to massage them into unit names (e.g.
by replacing dashes by dots). Also, if you have krunched file names, there is
no simple connection between the file name and the unit name.
If a unit spec contains a path, the HTML file for that unit is placed into that
directory unless overridden by a -o
option. Note that if the unit spec
contains a path, you'll most probably also have to set a -T
option, unless you do happen to have the ASIS information available
directly (i.e., a tree file for the unit in the current directory; but that's
not exactly typical).
In file input mode, the -o
option (if given at all) may either be
"-" (in which case all output goes to stdout) or specify a
directory, but must not specify a file.
assumes a GNAT-like naming scheme for source and HTML files. It
also assumes that there is one library unit per file. As of V1.4,
can handle krunched file names in the -f
provided it can find a source file, and it has the extension .ads
opens and parses the source file to extract the unit
name, instead of deriving it directly from the file name. Note that generated
files always have names based on the unit name, not the original file name:
i.e., output file names will never be krunched.
Generated HTML files always have the suffix ".html" (not
Index generation is active when adabrowse
is told to process several
units, and the output does not go to stdout (when the -o-
There are several options controlling index generation:
- -i or -is
- Switches on generation of a unit index.
- Switches on generation of a subprogram index.
- Switches on generation of a type index.
All these options take an optional filename as a parameter. If a filename
follows, the index will be written to that file (or to stdout, if the filename
happens to be "-"). If no filename is given, some default name is
All these options are actually maintained only for backwards compatibility
reasons. As of V4.0, indices are defined primarily through configuration file
entries, not on the command line. In order not to break existing scripts using
command line options of earlier adabrowse
versions, these options are
assumes it will process several units in the following cases:
- In file input mode (-f @file_name or
- When using a project file (-P
- When the -all option is given.
If no filename is given, or it doesn't contain a path, it depends upon the
setting of other options where the index will be placed:
- In file input mode, if a -o option is given, it must
specify a directory. All HTML files, including the index, will be put into
- If no -o option is given, but the first unit spec
contains a path, the index is put into the directory designated by that
- If not in file input mode, but the -all option has been
given, the -o option may specify a file name. The index is put into
the directory designated by the path part of that file name (the current
directory, if the filename doesn't contain a path).
- If using a project file, the indices are written into the
- Otherwise, this index is put in the current directory.
If a filename containing a path is given, the index will be placed into that
file in the given directory. If the filename contains only a path,
will use that path and create an index named
"index.html" in the designated directory.
If a -x
option is given (inhibiting overwriting of existing HTML files)
and a file exists already in the place where adabrowse
wants to put the
index, no index will be generated and adabrowse
will issue a warning.
It'll also warn if it cannot generate an index for any other reasons, but will
otherwise continue processing.
The full user's guide in /usr/share/doc/adabrowse.
and the accompanying documentation was written by Thomas Wolf
Ludovic Brenta <email@example.com> merely turned part of the
user's guide into this manual page for the Debian project.