C++ Source Code Parser - atostart

Purpose

The C++ Source Code Parser takes a set of C++ source files containing classes to generate template .otd C++ Test Driver Scripts and .otc C++ Contract Check Scripts to fully cover the application under test.

Syntax

atostart {[-i] <source file>} <options>

atostart {<source file>} -metrics <options>

where:

• <tested file> is the list of files containing classes to be tested. If no class if specified with the option -test_class, the tested classes will be either the classes defined in a file under test, or the classes for which a method is defined in a tested file.

• <options> is a series of command line options. See the section Options.

If a tested file is specified with option -i, this file will be included by the generated .otd script. As a consequence everything defined in this tested file will be available in the script (especially types, classes, static variables, and functions). This option is ignored if you choose not to generate an .otd C++ Test Driver Script.

Description

The tested files and additional files (see option -integrate) are parsed by the integrated C++ analyzer. A candidate classes list is automatically deduced from the content of tested files (this list can be viewed in the header of the generated .otd and .otc scripts). If no -test_class or -do_not_test_class option is used, then all the candidate classes will have generated code to test them.

The C++ Source Code Parser generates only one .otd C++ Test Driver Script that contains all classes under test. It also generates two files associated to this test script: a .dcl declaration file (declaring and including every resource needed to compile the test script) and a .stb stub file (containing stub declarations deduced from used but not defined entities found in the parsed files).

The C++ Source Code Parser generates one .otc C++ Contract Check Script per encountered .h file defining a class.

When the -metrics option is specified, the Source Code Parser produces static metrics for the specified source files.

Options

The C++ Source Code Parser supports the following options:

{-integrate <additional file>}

Specifies additional files or directories to be analyzed. These files do not contain any classes under test, but they do contain code which is to be linked with the tested application. Basically, this option tells the C++ Source Code Parser which files not to stub.

Three types of additional files or directories are supported :

• body files: Only the entities defined within the file are considered defined.

• header files: Every declaration within the file is considered as having a matching definition in a non-provided body file or in a library. Use additional header files when linking to code for which the source is not available.

• directories: Every declaration found in a file belonging to an additional directory is considered as having a matching definition in a non-provided body file or in a library (an additional directory can be viewed as a collection of additional header files).

Note A header file is recognized as such from its content, and not from its extension. A header file does not contain any definition, other than inline functions, and template functions, or else it is considered as a body file.

This option is ignored when no .otd generation is required. This option can be used more than once to specify multiple files.

{-insert|-i <included file>}

Specifies included files. These are source files which, instead of being compiled separately during the test, are included and compiled with the .otd test driver script.

In most cases, you do not have to specify files to be included. Header files are automatically considered as included files, even if they are not specified as such.

Source files under test should be specified as included when:

• The file contains the class definition of a class you want to test

• A function or a variable definition depends upon a type which is defined in the file under test itself

• You need access in your test script to a static variable or function, defined in the file under test

This option is ignored when no .otd generation is required. This option can be used more than once to specify multiple files.

-o|-otd <test script>

Specifies the name of the generated .otd script. Two associated files are also generated with the same name, but with extension .dcl and .stb. If the filename extension of <test script> is not .otd, then a warning is issued.

This option is ignored when no .otd generation is required.

-otc <test script>

Specifies the name of the generated .otc script. If the filename extension of <test script> is not .otc, then a warning is issued.

This option is ignored when no .otc generation is required.

-otcdir <OTC directory>

Specifies the directory where .otc files are to be generated.

This option is ignored when no .otc generation is required.

-opp <compiler option file>

Specifies the name of the Target Deployment Port C++ parser option file. This file is searched for in /ana subdirectory of the current Target Deployment Port (see ATLTGT environment variable), and should not include any path.

If this option is not provided, the default filename atl.opp will be searched for.

-hpp <compiler configuration file>

Specifies the name of the Target Deployment Port C++ parser configuration file. This file is searched for in /ana subdirectory of the current Target Deployment Port (see ATLTGT environment variable), and should not include any path.

If this option is not provided, the default filename atl.hpp will be searched for.

{-test_class|-tc <class under test>}

Specifies the classes to be explicitly tested. The classes must belong to the candidate classes. This option cannot be used simultaneously with the options -do_not_test_class (-dtc).

This option can be used more than once to specify multiple classes.

{-do_not_test_class|-dtc) <excluded class>}

Specifies the classes, among the candidate classes, which should not be tested. This option cannot be used simultaneously with the options -test_class (-tc).

This option can be used more than once to specify multiple classes.

-test_struct

Specifies whether structs and unions should be treated as classes, and therefore should be considered as potential tested classes. This option is not significant when -test_class option is used (you can specify structs or unions as classes to be tested).

-test_method|-tm <method name> <line>

Specifies the methods to be explicitly tested. <method_name> is the fully qualified name of the method (fully qualified class name with method name, without return values or parameters). <line> is the line number of the method. For example:

-test_method "class::method1" "50" "class::method2" "70"

This option can be used more than once to specify multiple methods.

-test_class_prefix <prefix>

Specifies the prefix used to name the generated test classes. By default, atostart uses 'Test'.

-test_each_instance

By default, a template class is tested as a generic template class. Use this option if you want to generate a specific test for each found instance of a template class.

{-force_template <template instance>}

This option forces the instantiation of the specified templates classes. Use it if no automatic template instantiation occurs while parsing the code. This option is useful only in conjunction with -test_each_instance option.

This option can be used more than once to specify multiple templates.

-overwrite

By default, the Test Template Generator creates a backup file of every file it overwrites. Use this option if you really intend to overwrite these files without backing up them.

-ignore_line_directives

Although the C++ test generator includes a preprocessor and can parse unpreprocessed source code, preprocessed code is also accepted. In the case of preprocessed source code, the test generator tries to detect included header files by looking at #line directives. In some cases, such as code generated by a code generator (for example lex or yacc), relying on #line directives does not produce effective test code. In this case, use -ignore_line_directives to have the generator ignore #line directives found in the source code.

Note In most cases, this option has no effect because unpreprocessed code does not usually contain #line directives.

This option is ignored when no .otd generation is required.

{-I<include directory>}

This option specifies directories where included files are to be searched for. You can use the option -I- to introduce the system includes: only directories specified after -I- will be looked up when the include directives use angular brackets (#include <…>).

This option can be used more than once to specify multiple directories.

{-D <macro>[=<value>]}

This option adds a predefinition for <macro> to <value>.

This option can be used more than once to specify multiple macros.

-E

This options generates preprocessing output to standard output. This option is mainly for debugging purpose.

-include={relative|absolute|copy}

This option specifies how #include directives should be generated in the test script. When relative is chosen, includes use relative path to the directory where the generated script is put. When absolute is chosen, absolute paths are generated. When copy is chosen, the way files are included in the test script is the same as they are included in the tested files, you should in this case ensure that the test script is generated in the same directory than the source files.

This option is ignored when no .otd generation is required.

-no_otc

This option deactivates .otc script generation. Use this option if you only want an .otd test driver script.

-no_otd

This option deactivates .otd script generation. Use this option if you only want an .otc Contract-Check script.

Note If no candidate class is found, nothing will be generated.

-studio_log

This option is for internal usage only.

Static Metrics Options

-metrics <output directory>

Generates static metrics for the specified source files. Resulting .met static metric files are produced in specified <output directory>. When the -metrics option is used, no other action is performed by the Source Code Parser.

-one_level_metrics

For use with the -metrics option only. When the -metrics option is used, by default, the calculation of static metrics is applied to the specified source files, and extended to any files included in those source files. Use the -one_level_metrics option to ignore included files when calculating static metrics.

-restrict_dir_metrics <directory>

For use with the -metrics option only. Use the the -restrict_dir_metrics option to calculate static metrics of the specified source files, extended to any files included in those source files but limited to those files located in the specified <directory>.

This option can be used more than once to specify multiple directories.

Return Codes

After execution, the program exits with the following return codes

All messages are sent to the standard error output device.