Locate_Complex_Expressions

This command locates expressions that exceed certain complexity thresholds. The following complexity metrics are computed:

• Nesting depth of the expression
• Total number of operators in the expression
• Total number of variable references
• Number of nonoperator function calls in the expression

A threshold parameter is available for each metric to limit which expressions are included in the hypertable output. Note that once an expression is found, its subexpressions will not be included even if they meet the selection criteria. The context in which the expression is located is also provided in the output.

Usage Tip: Although complexity is not inherently bad, it can lead to reduced readability and maintainability of programs and thus should be avoided when possible. Complexity can also indicate a high potential for error.

Command-Line Interface

Locate_Complex_Expressions

  -Minimum_Nesting_Depth [integer-expression, default = 3]

  -Minimum_Number_Of_Operators [integer-expression, default = 2]

  -Minimum_Number_Of_Variable_Refs [integer-expression, default = 2]

  -Minimum_Number_Of_Function_Calls [integer-expression, default = 0]

  -And_Threshold_Values

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/expression_complexity_analysis]

  <list of units>

Nonstandard Parameters

• Minimum_Nesting_Depth: Specifies the minimum expression depth required to be placed in the output table.
• Minimum_Number_Of_Operators: Specifies the minimum number of operators in the expression to be placed in the output table.
• Minimum_Number_Of_Variable_Refs: Specifies the minimum number of variable references in the expression to be included in the output table.
• Minimum_Number_Of_Function_Calls: Specifies the minimum number of calls to functions (nonoperator) to be included in the output table.
• And_Threshold_Values: Specifies that all minimums must be met for the expression to be included in the output. If this option is not selected, only one minimum threshold must be exceeded for the expression to be included in the hypertable output.

Sample Output

Locate_Constants

This command locates constant declarations and sorts them by value so that redundant values can be seen easily. Duplicate names are located and placed in a separate table.

Usage Tip: Location of redundant constant values can potentially improve code size. More importantly, it reduces confusion and program complexity.

Command-Line Interface

Locate_Constants

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/constant_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Note: Additional hypertables for fixed-point, string, character, enumeration, and access-type constants have the same content and format.

Duplicate Constant Names

Locate_Data_Synchronization_Points

This command takes as input reports generated by the Locate_Calling_-Thread_Sets_And_Uses command described on page 123. Its objective is to collate references to data items along several calling threads to locate variables that are set and/or used along multiple threads, and thus may require synchronization. The output report lists all data items found in all input reports, which threads reference the data item and how (set or use), and whether synchronization may be required.

Usage Tip: This command can be used to locate all variables that may require synchronized access. It can also be used as reference material to show which control threads reference a specific static variable.

Command-Line Interface

Locate_Data_Synchronization_Points

  -To_Report_Named [string-expression, default =

      <default_output_directory>/data_synchronization_analysis]

  <list of reports>

Nonstandard Parameters

• <list of reports>: Specifies a list of reports (.aarpt files) to compare for data items that are set and/or used in two different calling threads. This command will only process reports generated by the Locate_Calling_Thread_Set_And_Uses command.

Sample Output

Calling Thread Cross-Reference

Data Synchronization Points

Key for Synch column:

 No Synch:  No synchronization requried

 Potential Race: Synchronization not present but may be required to protect data integrity.

 Unreuirqed Synch: Synchronization present (protected variable) but not required.

Sync Protection:  Synchronization present (protected variable) and likey required.

Locate_Default_Initialization

This command locates types that contain default initialization (record types) and finds all object declarations of these types.

Usage Tip: Since elaboration code is generated for types with default initialization, this list helps locate all declarations that are initialized by default, thus allowing either the elimination of the default initialization or the explicit initialization in the declaration.

Command-Line Interface

Locate_Default_Initialization

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/default_initialization_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Locate_Elaboration_Impacts

This command locates all parts of the program that impact elaboration (that is, variables in a static scope with initialization, packages with begin blocks, task declarations, and pragma Elaborates). In addition, options are available to determine if a library unit is preelaborable (Ada 95 LRM 10.2.1 (5) or pure Ada 95 LRM 10.2.1 (16)).

Usage Tip: Occasionally the linker will have problems generating elaboration code, or the elaboration process will hang for some reason. This command provides insight into where program elaboration is located and, with other debugging aids, can help to locate the source of the problem.

Command-Line Interface

Locate_Elaboration_Impacts

  -Include_Task_Creations

  -Include_Static_Inits

  -Include_Package_Blocks

  -Include_Pragma_Elaborates

  -Include_Preelaboration_Analysis

  -Include_Pure_Analysis

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/elaboration_impact_analysis]

  <list of units>

Nonstandard Parameters

• Include_*: Specifies whether to include the * kind of elaboration construct.
• Include_Preelaboration_Analysis: Specifies whether or not to determine if a unit is preelaborable as defined by the Ada 95 LRM, section 10.2.1 (5).
• Include_Pure_Analysis: Specifies whether or not to determine if a unit is preelaborable as defined by the Ada 95 LRM, section 10.2.1 (16).

Sample Output

Static-Scope Initialization

Package Begin Blocks

Task Creation

Pragma Elaborate

Preelaboration Analysis

Key for "Unit Status" column: 

 Is Preelaborable:  Meets all criteria for a preelaborable unit.

 dependent on non-preelab Depends on a unit that is not preelaborable.

 executes statement:  Executes a statement other than a null statement.

 calls non-static function:  Calls subprogram other than a static function.

 references non-static object: References an object that is a non-static expression.

 default init with elab: Contains a default-initialized variable.

Pure Analysis

Key for "Unit Status" column: 

 Is Pure:  Meets all criteria for a pure unit.

 depends on non-pure: Depends on a unit that is not pure.

 contains variable:  Contains a variable declaration.

 contains access type:  Contains a named access type declaration.

Locate_Elements_Containing_Text

This command locates all instances of a textual string within the specified set of constructs.

Usage Tip: This command is similar to search command but it can search multiple Ada units at one time and can filter located text by the construct in which it appears.

Command-Line Interface

Locate_Elements_Containing_Text

  -Consider_Case

  -Search_Name_Declarations

  -Search_Name_References

  -Search_All_Expressions

  -Search_String_Literals

  -Search_Type_And_Subtype_Definitions

  -Search_Comments_Preceding_Elements

  -Text_To_Locate [string-expression, default = ""]

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/elements_containing_text_analysis]

  <list of units>

Nonstandard Parameters

• Consider_Case: Specifies that the Text_To_Locate should be considered case sensitive.
• Search_Name_Declarations: Specifies that an entry be added if text appears in a declarative name.
• Search_Name_References: Specifies that an entry be added if text appears in a reference to a name.
• Search_All_Expressions: Specifies that an entry be added if text appears in an expression.
• Search_String_Literals: Specifies that an entry be added if text appears in a string literal.
• Search_Type_And_Subtype_Definitions: Specifies that an entry be added if text appears in a type or subtype definition (that is, to the left of type T is or subtype St is).
• Search_Comments_Preceding_Elements: Specifies that an entry be added if text appears in a comment preceding a declaration or statement.
• Text_To_Locate: Specifies the text string to search for. This parameter will accept wildcard expressions. If a wildcard expression is specified for this option, then the string must match the comment line text or element image exactly. If no wildcards are present, the comment line or element image must only contain the Text_To_Locate to be reported. Thus, the wildcard text "*Bob*" would be equivalent to the non-wildcard text "Bob", but one could use more complicated expressions like "*help##doc*revised". See "Wildcards" on page 30 for a description of the available wildcard expressions.

Sample Output

Locate_Exceptions

This command locates exception declarations, raises, and handlers. This command also determines whether the exception is visible (that is, in a package specification).

Usage Tip: It is possible that a declared exception has no handler and/or no raise statements. Such problems must be fixed. Some projects discourage or prohibit the raising of predefined exceptions or the reraising of exceptions with the simple raise statement. Nonvisible exception declarations can be dangerous if they propagate out of scope. Occurrences of each of these issues can be seen easily with this command.

Command-Line Interface

Locate_Exceptions

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/exception_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Locate_Expensive_Types

This command locates type declarations that have the following attributes:

• Type declarations that are deeply nested
• Type declarations that have representation specifications
• Type declarations that are packed with pragma Pack
• Type declarations that are unconstrained

  Usage Tip: Deeply nested types, packaged types, and types with representation specifications can be expensive to use in that complicated address computations may be performed to extract individual data items. Unconstrained types typically require additional overhead (dope vectors and the like) and can therefore be expensive.

Command-Line Interface

Locate_Expensive_Types

  -Include_Unconstrained_Arrays

  -Include_Discriminant_Records

  -Include_Types_With_Rep_Specs

  -Include_Packed_Types

  -Include_Nested_Types

  -Minimum_Nesting_Level [integer-expression, default = 3]

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/expensive_type_analysis]

  <list of units>

Nonstandard Parameters

• Include_*: Specifies whether to include the * kind of construct in the hypertable output.
• Minimum_Nesting_Level: Specifies the minimum level of nesting required to be included in the hypertable output.

Sample Output

Nested Types

Unconstrained Types

Discriminant Record Types

Types with Representation Specifications

Packed Types

Locate_Expressions

This command locates expressions and collects general attributes of each expression. This command is most useful when locating all expressions of a particular kind that also match a particular pattern. If the compiler or linker has a problem with the implementation of a particular expression, this command can find all instances of those expressions.

Usage Tip: Since expressions are so common in Ada programs, this command can generate a tremendous amount of output. It is recommended that only specific constructs be included and that the number of units processed be limited. Only one example table is provided in the Sample Output section below. Other expression tables contains attributes specific to that expression.

Command-Line Interface

Locate_Expressions

  -Include_Indexed_Components

  -Include_Slices

  -Include_Selected_Components

  -Include_Character_Literals

  -Include_Integer_Literals

  -Include_Real_Literals

  -Include_Enumeration_Literals

  -Include_Null_Literals

  -Include_String_Literals

  -Include_Aggregates

  -Include_Type_Conversions

  -Include_Qualified_Expressions

  -Include_Allocators

  -Include_Complex_Expressions

  -Include_Function_Calls

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/expression_analysis]

  <list of units>

Nonstandard Parameters

• Include_*: Specifies whether to include the * kind of expression in the hypertable output.

Sample Output

Locate_External_Dependencies

This command locates dependencies that one set of Ada units has on another set. Dependencies are listed from a unit in the referencing set to a declaration in the referenced set.

Usage Tip: This command can be used to determine which interfaces in one library of code are used by units in another library. It can also show local library dependencies on each declaration in a unit. This information can be useful in restructuring code or determining when unwanted dependencies exist.

Command-Line Interface

Locate_Exernal_Dependencies

  -To_Declarations_In_Units [string-expression pathnames of referenced units]

  -Remove_Duplicates

  -Remove_In_Unit_Duplicates

  -Include_Unused_Declarations

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/external_dependencies_analysis]

  <list of units>

Nonstandard Parameters

• To_Declarations_In_Units: Specifies the set of referenced Ada units (that is, units that contain declarations referenced by the <list of units>). Items in the list must be separated by spaces. Pathnames of configuration files, views, directories, or specific Ada units can be included. If a configuration file is specified, all units in all views listed in the configuration file will be included in the analysis. If a view or directory is specified, all Ada units contained within that view or directory will be included in the analysis.
• Remove_Duplicates: Specifies whether to remove all duplicate references to a declaration, leaving only the first declaration reference in the report.
• Remove_In_Unit_Duplicates: Specifies whether to remove duplicate references that occur within the same referencing unit.
• Include_Unused_Declarations: Specifies whether to add another table to the report listing all declarations that are unused be the referencing units.
• <list of units>: In this case, a list of units with potential dependencies. These units can be in local or external subsystems. Pathnames of configuration files, views, directories, or specific Ada units can be included.

Sample Output

Unused Declarations

Locate_Generic_Complexities

This command locates the following program complexity associated with generics:

• Nested generics
• Generics instantiated with other generic instantiations
• Generics instantiated in dynamic scopes

  Usage Tip: The efficient use complex generic constructs often depends on the target compiler. Use of such constructs is not inherently bad but often difficult for some compilers to handle effectively.

Command-Line Interface

Locate_Generic_Complexities

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/generic_complexity_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Nested Generics

Generics Instantiated with Other Generics

Generic Instantiations in a Dynamic (Subprogram or Task) Scope

Locate_Generic_Formal_Dependencies

This command locates declarations in generic package declarations that do not depend (either directly or transitively) on one of the formal parameters of the generic.

Usage Tip: It is often possible to restructure the generic to include only those declarations dependent on the formals in a generic part and all other declarations in a nongeneric part. Code size (less expansion) can be saved when multiple instantiations exist.

Command-Line Interface

Locate_Generic_Formal_Dependencies

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/generic_formal_dependency_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Locate_Generics

This command locates all generic declarations and their instantiations. Up to the first three parameters (limited by space), actual and formal, are provided to show a comparison of various instantiations of the same generic.

Usage Tip: Grouping all instantiations of a generic interface makes it easier to note redundancy or perhaps opportunities to make more parts of the interface generic.

Command-Line Interface

Locate_Generics

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/generic_analysis]

  <list of units>

Nonstandard Parameters

All parameters are standard parameters.

Sample Output

Generic Packages

Note: The number of parameters in the output may vary (maximum of three) depending on the number present in the formals.

Generic Procedures

Generic Functions

Locate_Inline_Candidates

This command locates subprogram bodies and computes the following attributes:

• The number of statements in the subprogram body
• The number of declarations in the subprogram declarative part
• The number of calls on the subprogram
• Whether the subprogram has an exception handler

Thresholds can be designated to select only subprograms that have less than a maximum number of statements, declarations, or call sites. Subprograms with exception handlers can also be excluded. Subprograms with local task declarations are always excluded. Subprograms that are inlined already and either meet or do not meet the required threshold limits are also listed in a separate hypertable.

Usage Tip: Inlining can be key in optimizing programs designed with layers of abstraction. This command helps the user select which subprograms should and should not be inlined.

Command-Line Interface

Locate_Inline_Candidates

  -Include_Subprograms_With_Exception_Handlers

  -Include_Conforming_Subprograms_With_Inline

  -Include_Non_Conforming_Subprograms_With_Inline

  -Maximum_Statements [positive-expression, default = 5]

  -Maximum_Local_Variables [integer-expression, default = 10]

  -Maximum_Calls [integer-expression, default = 50]

  -Sort_By_Subsystem

  -Use_Configuration [string-expression, default = ""]

  -To_Report_Named [string-expression, default =

      <default_output_directory>/inline_candidate_analysis]

  <list of units>

Nonstandard Parameters

• Include_Subprograms_With_Exception_Handlers: Specifies whether to include subprograms with exception handlers as inline candidates.
• Include_Conforming_Subprograms_With_Inline: Specifies whether to list subprograms that already have inline pragmas and meet all thresholds and criteria.
• Include_Non_Conforming_Subprograms_With_Inline: Specifies whether to list subprograms that already have inline pragmas but do not meet all thresholds and criteria.
• Maximum_Statements: Specifies the maximum number of statements to be included as an inline candidate.
• Maximum_Local_Variables: Specifies the maximum number of local variable declarations to be included as an inline candidate.
• Maximum_Calls: Specifies the maximum number of calls on the subprogram to be included as an inline candidate.

Sample Output

Inline Candidates

See key for the Other column below.

Inlined Subprograms Exceeding Thresholds

Key for Other column:

 HAND:  Exception handler present

 RECUR:  Recursive subprogram

 TASK:  Task present