PowerAda areport

From OC Systems Wiki!
Jump to: navigation, search


NAME

areport - generate a sublibrary report

SYNOPSIS

areport [-h] [-BRW] [-y] [-L Library]
   [-s {-I | Sublibrary ...} | -l ]
   [ [-U | -F | -S | -N] [-t {lib|sec|pending}] 
   [-u {-I|Unit ...} | -f {-I|File ...}] |
   [-U | -F | -C | -T | -N ] -r Relationship 
   -u {-I|Unit...} ]

DESCRIPTION

areport generates reports that display different types of information about compiled units and sublibraries. This is the command-line equivalent to the Unit Reports operation in powerada.

The results are written to standard output. In general you use the areport command by specifying a type of input, a type of output and possibly a relationship between them. A type of input is specified with the lower case options such as -u, -f, -s, and -l. A type of output is specified with the upper case options such as -U, -F, and -S.

In this section and the following sections, a simple name is a file name not containing a "/" character. File names containing a "/" are called projects.

OUTPUT FIELDS

The result of a report depends on the information requested and the format specified. The following information is displayed by one or more of the reports:

Compilation Unit Name

A compilation unit name is always displayed with one of the following prefixes:

  • lib/ - a compiled library unit (specification)
  • sec/ - a compiled secondary unit (body or subunit)
  • pending/lib/ - a pending (loaded) library unit
  • pending/sec/ - a pending (loaded) secondary unit
  • inst/ - a compiled instance subunit

Object Module Name

The name of the object module in the sublibrary that contains the generated code for this compilation unit. This information is used by alibchk.

Source File Name

The fully-qualified filename of the source file from which this unit was loaded or compiled. A double-slash may appear in this name indicating which part of the name is within a project. This name may be changed after a file has been compiled using afilemv, though this may break some of the development tools that depend on the source location.

This field is shown if -F, -W, or -R are specified.

Unit Type

The unit type gives more information about the type of compilation unit. The following abbreviations are used:

  • Pac_S - package specification
  • Sub_S - subprogram specification
  • Pac_GS - generic package specification
  • Sub_GS - generic subprogram specification
  • Pac_IS - library package instantiation specification
  • Sub_IS - library subprogram instantiation specification
  • Pac_B - package body
  • Sub_B - subprogram body
  • Tsk_B - task body
  • Pro_B - protected unit body
  • Pac_GB - generic package body
  • Sub_GB - generic subprogram body
  • Pac_IB- library package instantiation body
  • Sub_IB - library subprogram instantiation body

Unit Date and Time

The date and time are given as two fields in a sortable format

yyyy/mm/dd hh:mm:ss

Generated Code Architecture

This indicates the target architecture for which code was generated. This is applicable only to compiled units, and is specified with the -qarch flag on the ada command.The possible values are:

  • com - common subset of PowerPC, POWER and POWER2 architectures (default)
  • ppc - PowerPC-specific instructions may be used
  • pwr - POWER-specific instructions may be used
  • pwr2 - POWER2-specific instructions may be used
  • N/A (not applicable) - the unit is pending, so no code was generated

Sublibrary Name

The fully-qualified name of the sublibrary from which the information was retrieved. This may be an otherwise-hidden delta sublibrary.

Compilation Options

The compilation options specified when the unit was compiled. This is shown on if -W or -R are specified

CM_Info

The string specified in a pragma CM_INFO or SCCS_ID in the source file. If not provided, the source file name is shown instead. This field is shown only if -W or -R are specified.

INPUT OPTIONS

-L Library
Specifies the library list file or root sublibrary within a project. The default is alib.list if the file exists or is outside the project; otherwise, the default is the sublibrary adalib.
-s Sublibrary . . .
Specifies a list of sublibrary names. The list ends either when another option is encountered or when the end of the command line is encountered. You can replace the list of names with -I, which signifies that the names are read from standard input. Each Sublibrary may be one of the following:
Specifies that the library list is checked for a sublibrary with the same simple name. If such a sublibrary exists in the library list, the possibly project specified in the library list is used. If no such library exists in the library list, the name is treated as the sublibrary name, relative to the current directory.
Specifies the relative or absolute path and name of the sublibrary. If -s is not specified, the default sublibrary (when a single sublibrary is needed) is the working sublibrary of whatever library list is being used (either the default or the list specified with -L).
-u Unit . . .
Specifies a list of units. The list ends either when another option is encountered or when the end of the command line is encountered. You can replace the list of names with -I, which signifies that the names are read from standard input. Unit names may start with lib/, sec/, pending/lib, pending/sec, inst/, or nothing (in which case both pending units and compiled units, library units and secondary units, and instance subunits will be displayed). If -r is specified, unit names must begin with one of the above prefixes.
-f File . . .
Specifies a list of file names. The list ends either when another option is encountered or when the end of the command line is encountered. You can replace the list of names with -I, which signifies that the names are read from standard input. Each file name that partially matches the specified file will be considered for the report. A partial match occurs if the specified file name exactly matches a file name, or if it matches only the last part of a file name after a "/".
-I
Specifies that a list of names is to be read from standard input. The names can be either compilation unit names, sublibrary names, or source file names depending on which of the -u, -s, or -f options you specify. When one of the -u, -s, or -f options is specified in this context to read names from standard input, the option must not be followed by a list of names.
For each invocation of areport, only one of the options -u, -s, and -f is allowed to have its list read from standard input.
If "--" is found in a line read from standard input, the rest of the line is ignored.
-l
Instead of listing specific sublibraries using the -s option, -l indicates that every sublibrary in the library is to be used except the system sublibrary.
-t { lib | sec | pending | inst }
Specifies that the report list show only pending units, library units, secondary units, or instance subunits. These can be abbreviated to as little as the first letter.
When -U is specified, each specified unit is displayed only if it is of the proper type. When -F is specified, only files containing units of the proper type are shown. When -S is specified, only sublibraries containing units of the proper type are shown.
This option cannot be used in combination with -r.
-y
Causes information from the system sublibrary to be reported along with any other sublibraries used. Normally, information from the system sublibrary is suppressed.

OUTPUT OPTIONS

The fields described in OUTPUT FIELDS above are displayed in different combinations depending on the options specified:

-B
brief: show only the first column, and no title line
-R
raw: show all fields in a fixed order separated by the pipe ('|') character for postprocessing.
-BR
suppresses the title line.

The order of fields shown (regardless of F, N, U) is:

  1. Compilation unit name
  2. Object module name
  3. Source file name
  4. Type
  5. Date
  6. Time
  7. Architecture
  8. Sublibrary Name
  9. Compile options
  10. CM_Info
-W
wide: show additional blank-separated fields
-C
Similar to the -F option except that the list of files is given in correct compilation order. Some information may be removed from the report since each file is only listed once. For files that contain more than one compilation unit, this list should be used with care since it may not always be correct. This flag must be used in conjunction with -r.
-F
filenames: show source file name in first column
-N
object names: show object module names in first column
-S
Indicates that a list of sublibrary names is desired. Only the sublibrary name is given. This option is useful for generating a library list file from a root sublibrary within a project with the command areport -L adalib -BSl.
-T
Similar to the -U output except that the units are displayed in a tree structure to indicate dependencies. An example of this follows, where the extended family of a unit is reported. This flag must be used in conjunction with "-r".
--Comp unit name  (Type)  Date       Time       Sublibrary
*lib/p11       -- (Pac_S) 1997/06/30 07:00:37   adalib
    | lib/p8   -- (Pac_S) 1997/06/30 09:07:03   adalib
    | | sec/p8 -- (Pac_B) 1997/06/30 09:07:03   adalib
    | sec/p11  -- (Pac_B) 1997/06/30 07:00:40   adalib

obsolete units (which should be recompiled) are indicated with "*" in the first column. Missing units are indicated with "?" in the first column.

-U
unit names: show compilation unit names in first column (deSelecting the Type of Output

RELATIONSHIP OPTIONS

By default, areport examines a given set of units and displays information about just those units. It can also look at relationships between units, and display information about sets of related units. For example, instead of reporting the names of the source files containing a given set of units, areport can report the names of source files that contain the given units or any others that depend on them. The terms that describe these relationships are defined in the glossary.

-r Relationship
Specifies a relationship that is to be used to determine what is to be reported. All units related to the given units by Relationship are considered for the report. For reports using -U, -F, or -C, the Relationship can be one of the following:
{ family  | extended 
  imports | supporters | exports | dependents |
  current | linkable | elaboration }

For reports using -T, the Relationship can be one of the following:

{ family | extended | supporters | dependents }

For each unit specified with the -u option, a report is generated according to the Relationship specified:

  • family Indicates that the given unit's family is to be determined. The minimum allowed abbreviation is f.
  • extended Indicates that the given unit's extended family is to be determined. The minimum allowed abbreviation is "ex".
  • imports Indicates that those units "withed by" the given units are to be shown. The minimum allowed abbreviation is i.
  • supporters Indicates that the given unit's supporters are to be determined. The minimum allowed abbreviation is s.
  • exports Generates a list of units or files that "with" the specified units. The minimum allowed abbreviation is exp.
  • dependents Generates a list of units or files that are dependent on the given units. The minimum allowed abbreviation is d.
  • current Generates a list of all units (or files) that must be compiled to make the specified unit "current", so that all the library units it depends on are in the sublibrary and the compilation order is correct. The bodies for some library units may be missing. The minimum allowed abbreviation is c.
  • linkable Generates a list of all units (or files) that must be compiled to make the specified unit "linkable", so that all the library units it depends on, and their bodies, are in the sublibrary and are compiled in the correct order. At this point, the sublibrary contains all the object code needed to link an executable program. The minimum allowed abbreviation is l.
  • elaboration Generates a list of units or files in the order in which the compilation units will be elaborated. The minimum allowed abbreviation is el.

FILES

$POWERADA/bin/areport - the areport program image

RETURN CODES

Following is a list of the possible values returned by areport. Refer to Return Codes for Commands for details about the meaning of these return s.

0, 1, 2, 3, 4, 5, 25, 26, 27, 99

ENVIRONMENT VARIABLES

POWERADA
This must be defined and indicate the powerada/ada95 directory in the PowerAda installation.
POWERADA_BASELINES
Names a baselines file identifying aliases for baseline projects.

EXAMPLES

Here are some more examples of the areport command. In each command, the input options are given, followed by the relationship options, followed by the output options, if any.

  1. To list the units in the working sublibrary, enter:

    areport
  2. To print the names of all the units in file test.ada (in the working sublibrary), enter:

    areport -f test.ada -UB
  3. To search your library for the name of the file containing the specification of test, enter:

    areport -lu lib/test -FB
  4. To print the list of units that depend on lib/test, enter:

    areport -lu lib/test -r dependents -B
    
  5. To print the list of files that need to be compiled in order to bind and link unit sec/main into an executable, in the correct compilation order, enter:

    areport -lu sec/main -r linkable -CB

SEE ALSO

abuild, aprojbuild, powerada.

BUGS/LIMITATIONS

See Problems and Questions at the beginning of this Appendix.