Ada Instrumentor - attolada

Purpose

The source code insertion (SCI) Instrumentor for Ada inserts functions from a Target Deployment Port library into the Ada source code under test. The Ada Instrumentor is used for Code Coverage only.

Syntax

attolada <src> <instr> [<options>]

where:

• <src> is the source file (input)

  <instr> is the instrumented output file

Description

The Instrumentor builds an output source file from an input source file, by adding special calls to the Target Deployment Port function definitions.

The Ada Instrumentor (attolada) supports Ada83 and Ada95 standard source code without distinction.

You can select one or more types of coverage at the instrumentation stage (see the User Guide for more information).

When you generate reports, results from some or all of the subset of selected coverage types are available.

Options

-PROC [=RET]

-PROC alone instruments procedure, function, package, and task entries. This is the default setting.

The -PROC=RET option instruments both entries and exits.

-CALL

Instruments Ada functions or procedures.

-BLOCK [=IMPLICIT | DECISION | LOGICAL | ATC]

This option specifies how blocks are to be instrumented.

• The -BLOCK option alone instruments simple blocks only.

  Use the IMPLICIT or DECISION option to instrument implicit blocks (unwritten else instructions), as well as simple blocks.

  Use the LOGICAL parameter to instrument logical blocks (loops), as well as the simple and implicit blocks.

  Use the ATC parameter to extend the instrumentation to asynchronous transfer control (ATC) blocks.

By default, the Instrumentor instruments implicit blocks.

-COND [=MODIFIED | COMPOUND | FORCEEVALUATION]

When -COND is used with no parameter, the Instrumentor instruments basic conditions.

• MODIFIED or COMPOUND are equivalent settings that allow measuring the modified and compound conditions.

  FORCEEVALUATION modifies the code to force the execution of all conditions in the decision.

-NOPROC

Disables instrumentation of procedure inputs, outputs, or returns, etc.

-NOCALL

Disables instrumentation of calls.

-NOBLOCK

Disables instrumentation of simple, implicit, or logical blocks.

-NOCOND

Disables instrumentation of basic conditions.

-NOFULLPATHKEY

This option forces the product to ignore the full path of files. Use this option if you need to consolidate test results when a same file can be identified with various paths, for example in a multi-user development environment using source control.

-UNIT=<name>[{,<name>}] | -EXUNIT=<name>[{,<name>}]

-UNIT specifies Ada units (packages or functions or procedures in packages) whose bodies are to be instrumented, where <name> is an Ada unit which is to be explicitly instrumented. All other functions are ignored.

-EXUNIT specifies packages, or functions or procedures in packages that are to be excluded from the instrumentation. All other Ada units are instrumented. Units that are excluded from the instrumentation process with the -EXUNIT option are still analyzed. Any errors found in those files are still reported. For example: -EXUNIT=MYPACKAGE or -EXUNIT=MYPACKAGE.MYFUNCTION

-UNIT and -EXUNIT cannot be used together.

-LINK= <filename>[{,<filename>]]

Provides a set of link files to the Instrumentor.

-INJECT= <unit>[{,<unit>]]

-NAMEINJECT[=<name>]

These options allow you to inject a procedure definition into the instrumented source code. -INJECT specifies the package(s) that contain the procedure definition. -NAMEINJECT specifies the name of the procedure that is injected. If <name> is not specified, then the procedure name ATTOL_TEST is assumed. These options must be used together.

-STDLINK= <filename>

Provides a standard link file to the Instrumentor.

-FDCDIR= <directory>

Specifies the destination <directory> for the .fdc correspondence file, which is generated for Code Coverage after the instrumentation for each source file. Correspondence files contain static information about each enumerated branch and are used as inputs to the Code Coverage Report Generator. If <directory> is not specified, each .fdc file is generated in the directory of the corresponding source file. If you do not use this option, the default .fdc files directory is the working directory (the attolada execution directory). You cannot use this option with the -FDCNAME option.

-FDCNAME= <name>

By default, the instrumentor generates one .fdc static correspondence file for each source file involved in the code to be instrumented. Use this option to specify a single static file for all source files in order to avoid file access conflicts, for example when a parallel build is involved. When this option is specified, the generated .fdc file contains one FDC section per source file. You cannot use this option with the -FDCDIR option.

-DUMPINCOMING= <name>[{,<name>}]

-DUMPRETURNING= <name>[{,<name>}]

These options allow you to explicitly define upon which incoming or returning function(s) the trace dump must be performed. Please refer to General Runtime Analysis Settings in the User Guide for further details.

-COMMENT= <comment>

Associates the text from either the Code Coverage Launcher (preprocessing command line) or from you with the source file and stores it in the FDC file to be mentioned in coverage reports. In Code Coverage Viewer, a magnifying glass is put in front of the source file. Clicking on this magnifying glass, shows this text in a separate window. The comment text must not contain commas or non-alphanumeric characters.

-NOMETRICS

Saves the metrics basic data calculation time.

-RESTRICTION =NOEXCEPTION|NOGENERIC|CSMART

Use this option to set a restriction.

• NOEXCEPTION deactivates instrumentation of exception block branches encountered in the source file. When this option is active, no coverage information is available on exception blocks or on instructions contained in exception blocks.

  NOGENERIC deactivates the instrumentation using a generic Target Deployment Port call. When this option is active, the generated source code may contain uninstrumentable calls. If used with the -CALL option, this can generate compilation errors depending on your application if, for example, you use private packages as well as private sub-packages.

  CSMART generates CSMART compliant code.

-NOSOURCE

Replaces the generation of the colorized viewer source listing by a colorized viewer pre-annotated report containing line number references.

-NOCVI

Disables generation of a Code Coverage report that can be displayed in the Code Coverage Viewer.

-METRICS

Provides static metric data for compatibility with old versions of the product. Use the static metrics features of the Test Script Compiler tools instead. By default no static metrics are produced by the Instrumentors.

-GENERATEDNAME = CHECKSUM | <filename>

-USERNAME = <NAME>

Use these options to add a package to the header of the generated file to store coverage traces. You can specify the name of the generated package using one of the following three options:

• -GENERATEDNAME=CHECKSUM uses a checksum calculated on the instrumented file to create a package name under the form ATC_ <checksum>, where <checksum> has a maximum of four letters.

  -GENERATEDNAME= <filename> uses the name of the file to be instrumented, this name is transformed into an Ada identifier and prefixed by ATC_.

  -USERNAME= <username>: A name you choose freely by the user and provide on the command line.

<File> is used without checking whether it is a valid Ada identifier.

By default, the -GENERATEDNAME=<FILE> option is used.

-ALTCHECKSUM

Use this option to calculate a more unambiguous checksum for .fdc and .tsf files. Before using this option, you must delete existing fdc and tsf files, which will be re-created with the new checksum. File keys are not changed by this option.

-PREFIX= <prefix>

You can prefix some instrumentations (name of the generated package, variables, etc.) if there are any semantic ambiguities. Thus, packages generated by attolada can be recognized by giving them a known prefix.

By default, no prefix is used.

Note The prefix you provide is used, without checking whether it is a valid Ada identifier.

-SPECIFICATION

Extends instrumentation of calls and conditions to source code inside package specifications.

-MAIN= <unit>[{, <unit>}]

Forces a trace dump at the end of the main unit of your application.

-EXCALL= <unit>[{, <unit>}]

Only applies when -CALL is used. Excludes all specified calls to the function or procedure units from the instrumentation. The <unit> names must be fully qualified names, for example: package.procedure

-ADA83 | -ADA95

Choose specifies the Ada language used by the Instrumentor. This language is applied to the analyzed and generated file.

-INSTRUMENTATION=[COUNT|INLINE]

Specifies the Instrumentation Mode:

• COUNT: Default Pass mode, each branch generates in 32 bits for profiling purposes. This offers the best compromise between code size and speed overhead.

• INLINE: Compact mode. functionally equivalent to Pass mode, except that each branch needs only one bit of storage instead of one byte. This implies a smaller requirement for data storage in memory, but produces a noticeable increase in code size (shift/bits masks) and execution time.

By default, count mode is used, which is a compromise between the flow mode (everything is a call to the Target Deployment Package) and the inline mode (when possible, the code is directly inserted into the generated file).

-NOINFO

Asks the Instrumentor not to generate the identification header. This header is normally written at the beginning of the instrumented file, to strictly identify the instrument used.

-STUDIO_LOG

This option is for internal usage only.

Return Codes

After execution, the program exits with the following return codes

All messages are sent to the standard error output device.