Working with Auto CCT Scripts

The Auto CCT feature uses a collection of python scripts to generate a CCT. The scripts are called filters.

There are a number of key classes in most filters:

  • Configurator - The configurator contains miscellaneous features of the CCT such as the target, hierarchy or compiler name. It can also specify various flags for the parsers such as the size and alignment values. See Configurator Class.
  • CCTData - There is usually a CCT data class for C and one for C++. Functions in this class can add defines, specify general CCT options, add macro definitions and so on. See CCTData Class.
  • Visitor class (option processing) - The visitor class processes command line arguments. See Visitor Class (Option Processing).

The classes must be passed to the filter_init function. Refer to The filter_init Function and Filter Setup for more information.

A guide to creating a filter from scratch is here. Refer to Adding a New Compiler for more information.

Debugging

When working with the filters, it is recommended to set the Perforce QAC log level to TRACE. This will cause verbose debugging information to appear in the log files or on the output from qacli. Stack traces from python will be shown in the event of an error.

Filters can call the debug function to write information to the log. Adding new debug calls can help track down a problem.

Usually it will be sufficient to use qacli to invoke the generator. It may help sometimes to see exactly what that does. By looking in the log file, you can see that it calls a script called cctgen.py which in turn invokes the qainject binary. With the log level set to TRACE, it is possible to see how these processes are invoked so that they can be called independently of qacli.

Filter Location and qafilter.conf

The filters are stored with the shipped CCT's. They are copied from the installation folder to the users local data when Framework first starts. For Windows, the locations would be:

C:\Perforce\QAC-<version>\config\cct\cctgen\qainject_filters

and

%LOCALAPPDATA%\Perforce\QAC-<version>\config\cct\cctgen\qainject_filters

The folder contains all the filters and also qafilter.conf, which is a file describing which filter is used for a given executable. For example, the lines to invoke the qa_icc_filter.py file for any executable that starts with icc is:

# IAR compilers
filter qa_icc   icc*

The comment line (starting with a # character) is used by the qacli help -a command, which shows all the supported filters, to display the name of the compiler.

Example CCT

This is an example CCT with information on which function controls the output of the section. It is a TI CCT with some sections or settings reduced for brevity. 

{
 "PLATFORM" : "PLATFORM_WIN64",
 "COMPILER_HIERARCHY" : "TI",
 "COMPILER_NAME": "ARMCL",
 "COMPILER_VERSION": "20.2",
 "HOST": "x64",
 "TARGET": "ARM",
 "SOURCE_LANGUAGE": "C",
 "COMPILER_CMD": "c:\\ti\\ccs1110\\armcl.exe",
 "COMPILER_ADDITIONAL_ARGS" : ["--plain_char=signed"],
 "ADDITIONAL_INCLUDES": "DATA/autocct/Stub/TI_C",
 "INCLUDE_LIST" : [
    {"INCLUDE_STRUCTURE": {
       "INCLUDE_TYPE": "MasterScript",
       "INCLUDE_VALUE": "DATA/autocct/Script/master_script.py"
      }
    }],
  "SYNCHRONIZATION" : {
    "INCLUDE_FLAGS":"-I",
    "DEFINE_FLAGS":"-D",
    "SETTINGS_FILE_OPTIONS": {
      "FLAG":"-@,--cmd_file=",
      "EXTENSION":",",
      "LITERAL_QUOTES":","
     }
   }
 }
  • PLATFORM is either PLATFORM_WIN64 or PLATFORM_LIN64 depending on the current OS
  • COMPILER_HIERARCHY comes from the hierarchy function in the Configurator
  • COMPILER_NAME can come from the parameter to filter_init or can be overriden by user_visible_name in the Configurator
  • COMPILER_VERSION is extracted from the compiler with parameters given to filter_init
  • HOST is either x64 or x86 depending on the host computer.
  • TARGET, in this case, comes from the Configurator.
  • SOURCE_LANGUAGE is determined by the file extension.
  • COMPILER_CMD is the path to the compiler binary.
  • COMPILER_ADDITIONAL_ARGS are the parameters from the first compile command with certain options removed as controlled by the ignore_options parameter to the filter_init function.
  • ADDITIONAL_INCLUDES comes from the additional_include function in CCTData.
  • INCLUDE_STRUCTURE, in this case, comes from the masterscript_include in CCTData. It is the path to the CIP generation script.
  • SYNCHRONIZATION settings are not relevant to Auto CCT which already knows what the various compiler flags do and performs it's own synchronization. These settings are generated just in case a generated CCT is then used for a different synchronization method.
  • INCLUDE_FLAGS comes from include_flags in CCTData and DEFINE_FLAGS comes from define_flags in CCTData.
  • SETTINGS_FILE_OPTIONS comes from get_settings_file_options in CCTData.
* compiler behavior
* parsing extensions
-xn 16384
-na 16384
-ar+
-ex ansipc
-ex pc
-ex asm
-ex longlong
-fpc+
-sl-
-xc-

The parsing extension section comes from the parser_extensions function in CCTData.

* CIP replacement
-q "C:\ti\ccs1110\ccs\tools\compiler\ti-cgt-arm_20.2.5.LTS\include\libcxx"
-si "C:\ti\ccs1110\ccs\tools\compiler\ti-cgt-arm_20.2.5.LTS\include\libcxx"
-q "C:\ti\ccs1110\ccs\tools\compiler\ti-cgt-arm_20.2.5.LTS\include\libcxx\ext"
-si "C:\ti\ccs1110\ccs\tools\compiler\ti-cgt-arm_20.2.5.LTS\include\libcxx\ext"

If the CIP is not generating the compiler include paths, the _generates_cip_includes member variable in the Configurator must be set to True.

Once this is set, the result of the read_includes function (passed to the filter_init function) is used to generate this section.

* preprocessor symbol definitions
-sd __intaddr__="1 prl_ignore_paren"
-sd __interrupt=""
-sd interrupt=""
-sd __LONG_LONG_MAX__="9223372036854775807"
-sd __LONG_MAX__="2147483647"
-sd _OPTIMIZE_FOR_SPACE="1"
-sd __PRAGMA_REDEFINE_EXTNAME="1"
-sd prl_ignore_paren="_ignore_paren"
-sd _PRL_STRINGIFY(x)="#x"
-sd __PTRDIFF_T_TYPE__="int"
-sd __signed_chars__="1"
-sd __SIZE_T_TYPE__="unsigned"
-sd __SIZEOF_DOUBLE__="8"
-sd __SIZEOF_FLOAT__="4"
-sd __SIZEOF_INT__="4"
-sd __SIZEOF_LONG__="4"
-sd __STDC__="1"
-sd __STDC_VERSION__="199409L"
-sd __TI_VFPLIB_SUPPORT__="1"
-sd __TI_WCHAR_T_BITS__="16"
-sd __TIME__=_PRL_STRINGIFY("13:10:40")
-sd __TIMESTAMP__="__DATE__ __TIME__"
-sd __TMS470__="1"
-sd __va_argcsu="1 prl_ignore_paren"
-sd __va_argref="1 prl_ignore_paren"
-sd __VERSION__=_PRL_STRINGIFY("EDG gcc 4.8 mode")
-sd __WCHAR_T_TYPE__="unsigned short"

Most of these settings are the result of asking the compiler for a list of predefined macros. They usually come from running the compiler with the info_args parameter of the filter_init function. Alternatively, the read_defines function (passed to filter_init) is used.

The other values come from extra_defines in CCTData.

* intrinsic types
-it ptrdiff_t="int"
-it size_t="unsigned"
-it wchar_t="unsigned short"

The intrinsic types come from the type_mappings function in CCTData.

* basic type size and alignment
-s char="8"
-a char="1"
-s double="64"
-a double="8"
-s float="32"
-a float="4"
-s int="32"
-a int="4"
-s ldouble="64"
-a ldouble="8"
-s long="32"
-a long="4"
-s longlong="64"
-a longlong="8"
-s short="16"
-a short="2"

The type sizes and alignment section is calculated from size_type_map in CCTData.

* qac parser options
-bits-
-ex c++
-ex dollar
-u-

The TI filter's Visitor class inherits from the GNU Visitor class which defaults to having settings for bits, ex dollar and u.

For information on these settings, see _qac_parser_options and signed_char_defines.

The -ex C++ flag is added by the system for C source code when the version is not c90.