C and C++ Instrumentation Launcher - attolcc
The Instrumentation Launcher instruments and compiles C and C++ source files. The Instrumentation Launcher is used by Memory Profiling, Performance Profiling, Runtime Tracing and Code Coverage, as well as the Component Testing Contract Check feature for C++.
attolcc [{<-options>}] [{<-settings>}] -- <compilation_command>
attolcc --help
where:
<compilation_command> is the standard compiler command line that you would use to launch the compiler if you are not using the product
"--" is the command separator preceded and followed by spaces
<options> is a series of optional parameters
<settings> is a series of optional instrumentation settings
The Instrumentation Launcher fits into your compilation sequence with minimal changes.
The Instrumentation Launcher is suitable for use with only one compiler and only one Target Deployment Port. To view information about the driver, run attolcc with no parameters.
The attolcc binary is located in the /cmd directory of the Target Deployment Port.
Note Some Target Deployment Ports do not have an attolcc binary. In this case, you must manually run the instrumentor, compiler and linker.
The Instrumentation Launcher accepts all command line parameters for either the C or C++ Instrumentor, including runtime analysis feature options. This allows the Instrumentation Launcher to automatically compile the selected Target Deployment Port.
In addition to Instrumentor parameters and Code Coverage parameters, the following options are specific to the Instrumentation Launcher. Command line options can be abbreviated to their shortest unambiguous number of characters and are not case-sensitive.
--HELP
Type attolcc --help to list a comprehensive list of options, including those of the instrumentor, for use with the instrumentation launcher.
-VERBOSE | -#
The -VERBOSE option shows commands and runs them. The "-#" option shows commands but does not execute them.
-TRACE
-MEMPRO
-PERFPRO
These options activate specific instrumentation for respectively the Runtime Tracing, Memory Profiling and Performance Profiling runtime analysis feature.
-OTIFILE=<file>[{,<file>}]
When using the Contract Check capability of Component Testing for C++, the -OTIFILE option allows you to specify one or several Component Testing .oti instrumentation files for C++. These files are generated by the C++ Test Compiler and contain the Component Testing instrumentation rules for C++.
-AUTO_OTI
When using the Contract Check capability of Component Testing for C++, this option specifies that Component Testing instrumentation files (.oti) for C++ are to be searched and loaded from the directory specified with option -OTIDIR, or in current directory if this option is not used. .oti files are searched according to the source file names. For instance, if class A is found in file myfile.h, the .oti searched will be myfile.oti. An information message is issued for each .oti file loaded automatically.$
-FORCE_TDP_CC
This option forces the Instrumentation Launcher to attempt to compile the Target Deployment Port even if the link phase has not yet been reached before the TP.o or TP.obj is built.
-NOSTOP
This option forces the initial command to resume when a failure occurs during preprocessing, instrumentation, compilation or link. This means that the build chain is not interrupted by errors, but the resulting binary may not be fully instrumented. Use this option when debugging instrumentation issues on large projects.
Each error is logged in an attolcc.log file located in the directory where the error occurred.
The following parameters are specific to the Code Coverage runtime analysis feature. These options do not activate Code Coverage. To activate Code Coverage, use the Code Coverage Level options (-PROC, -CALL, -COND and -BLOCK).
-PASS | -COUNT | -COMPACT
Pass mode only indicates whether a branch has been hit. The default setting is pass mode.
Count mode keeps track of the number of times each branch is exercised. The results shown in the code coverage report include the number of hits as well as the pass mode information.
Compact mode is equivalent to pass mode, but each branch is stored in one bit, instead of one byte as in pass mode. This reduces the overhead on data size.
-COMMENT | -NOCOMMENT
The comment option lets the user associate a comment string with the source in the code coverage reports and in Code Coverage Viewer.
By default, the Instrumentation Launcher sends the preprocessing command as a comment. This allows you to distinguish the source file that was preprocessed and compiled more than once with distinct options.
Use -NOCOMMENT to disable the comment setting.
-metrics=<output directory>
Generates static metrics for the specified source files in the specified <output directory>. This option replaces the metcc command line tool, which is deprecated.
-one_level_metrics
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>
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>.
-studio_log
This option is for internal use only.
The instrumentation settings apply to the compilation of the Target Deployment Port Library.
The 0 or 1 values for many conditional settings mean false for 0 and 1 for true.
--cflags=<compilation flags>
--cppflags=<preprocessing flags>
--include_paths=<comma separated list of include paths>
--defines=<comma separated list of defines>
Enclose the flags with quotes ("") if you specify more than one. These flags are used while compiling the Target Deployment Port Library
By default, the corresponding DEFAULT_CPPFLAGS, DEFAULT_CFLAGS, DEFAULT_INCLUDE_PATHS and DEFAULT_DEFINES from the <ATLTGT>/tp.ini or <ATLTGT>/tpcpp.ini file are used
--atl_multi_threads=0|1
To be set to 1 if your application is multi-threads (default 0).
--atl_threads_max=<number>
Maximum number of threads at the same time (default 64).
--atl_multi_process=0|1
To be set to 1 if your application uses fork/exec to run itself or another instrumented application (default 0). Traces files are named atlout.<pid>.spt.
--atl_buffer_size=<bytes>
Size of the Dump Buffer in bytes (default 16384).
--atl_traces_file=<file-name>
Name of the file that is flushed by execution and to be split (default atlout.spt).
--atp_call_stack_size=<number of frames>
Number of functions from the stack associated to any tracked memory block or to any error (default 6).
--atp_reports_fiu=0|1
File In Use detection and reporting (default 1)
--atp_reports_sig=0|1
POSIX Signal detection and reporting (default 1).
--atp_reports_miu=0|1
Memory In Use detection and reporting, ie: not leaked memory blocks (default 0).
--atp_reports_ffm_fmwl=0|1
Freeing Freed Memory and Late Detect Free Memory Write detection and reporting (default 1).
--atp_max_freeq_length=<number of tracked memory blocks>
Free queue length, ie: maximum number of tracked memory blocks whom actual free is delayed (default 100).
--atp_max_freeq_size=<bytes number>
Sets the free queue size, ie: the maximum number of bytes actually unfreed (default 1048576 = 1Mb)
--atp_reports_abwl=0|1
Late Detect Array Bounds Write detection and reporting (default 1).
--atp_red_zone_size=<bytes number>
Size of each of the two Red Zones placed before and after the user space of the tracked memory blocks (default 16).
--atq_dump_driver=0|1
Enable the Performance Profiling Dump Driver API atqapi.h (default 0).
--atc_dump_driver=0|1
Enablesthe Coverage Dump Driver API apiatc.h (default 0).
--att_on_the_fly=0|1
If set to 1, implies that each tdf lines are flushed immediatly in order to be read on-the-fly by the UML/SD Viewer in Studio (default 0).
--att_item_buffer=0|1
Enable Trace Buffer (not Dump Buffer) if set to 1 (default 0).
--att_item_buffer_size=<bytes>
Maximum number of recorded Trace elements before Trace Buffer flush (default 100).
--att_partial_dump=0|1
Partial Message Dump is on if set to 1 (default 0).
--att_signal_action=0|1|2
0 means no action when handling a signal (default)
1 means toggling dump of messages
2 means only flushing the current call stack
--att_record_max_stack=0|1
Display largest call stack length in a note (default 1).
--att_timestamp=0|1
If enabled, record and display time stamp (default 0).
--att_thread_info=0|1
If 1 record and display thread information (default 1).
--atk_stop_on_error=0|1
Call breakpoint function on assertion failure (default 0).
--atk_dump_success=0|1
By default (0), only failed assertions are reported. If enabled, both failed and passed assertions are reported.
--atk_report_reflexive_states=0|1
Trace unchanged states (default 1).
attolcc -- cc -I../include -o appli appli.c bibli.c -lm
attolcc -TRACE -- cc -I../include -o appli appli.c bibli.c -lm
The return code from the Instrumentation Launcher is either the first non-zero code received from one of the commands it has executed, or 0 if all commands ran successfully. Due to this, the Instrumentation Launcher is fully compatible with the make mechanism.
If an error occurs while the Instrumentation Launcher - or one of the commands it handles - is running, the following message is generated:
ERROR : Error during C preprocessing
All messages are sent to the standard error output device.
Related Topics
Environment Variables