HOME Generic Build Support (GBS) - User Manual
The audit.gbs files

Contents

Description

Purpose

The audit.gbs files are located in the GBS_SYSAUDIT_PATH/audit directories and are used to associate file-extensions with audit-plugins (QAC, QAC++ etc) for a specific audit.
Also the particularities of the auditing plugins are defined.

General

Additional for this file:

• Lines with no leading white-space (called header-lines) define an item.
• Following lines with leading white-space (called sub-lines) define the parameters for that item.
• Reserved words (keywords) are case sensitive
• The search path for the .include Directive is:
  - $GBS_SYSAUDIT_PATH/$GBS_AUDIT
  - $GBS_SYSAUDIT_PATH

Contents

SETUP Definition

Purpose:

To define general stuff, valid for the whole definition set.

Syntax:

SETUP

NICE_NAME = nice_name

VIA_FORMAT = via_format

Semantics:

NICE_NAME

Specifies a more descriptive name of the Audit. It is used in messages.

nice_name

Free format (just do not make it too long)

VIA_FORMAT

Specifies format/syntax of file-inclusion on the command-line.

via_format

Specifies the printf format for command-line file-inclusion
It must contain a %s
It may contain a .file_type
If a .file_type is not specified .gbs will be used.
e.g.: -via %s for QAC,
%s.lnt for PC-Lint,
@%s for MVS or
%s (default)

INIT Definition

Purpose:

To perform general initialisation.
It is possible to define derived plugin dependent Environment Variables
Note that all references to the 'outside-world' must be specified in the switch.gbs.
On Windows it can be used to (re)define an EnvVar with spaces removed. (Converted to ShortPathName)

Syntax:

INIT

SET_W = envvar_name => envvar_value

...

SET_X = envvar_name => envvar_value

...

SET = envvar_name => envvar_value

...

SETPATH = path_envvar_name => envvar_value-list

...

BIN_DIR = bin_dir

COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition

...

Semantics:

SET_W, SET_X & SET

Specifies an Environment Variable.

envvar_name

Uppercase please

envvar_value

If placed between quotes (") it will be canonicalised (/.. solved) and on Windows converted to a ShortPathName without spaces.

SET_W is executed for Windows only.
SET_X is executed for Linux only.
SET is executed for all platforms
and must be specified after SET_W and SET_X

SETPATH

Specifies a PATH Environment Variable.

path_envvar_name

Case dependent on OS

envvar_value-list

If placed between quotes (") items will be canonicalized (/.. solved) and on Windows converted to a ShortPathName without spaces.
Items will be properly joined (';' on Windows, ':' on Linux)

Must be specified after SET_W, SET_X & SET

BIN_DIR

Specifies the directory in which the executables of the plugin reside, relative to GBSEXT_<plugin>_PATH.
It is used to assemble GBSEXT_<plugin>_BIN_PATH which must be used in the COMMAND sub-section.

bin_dir

One or more directories, separated by '/'

COMMAND

Command for general initialisation.
Note that any EnvVars set during execution of the command will be lost when the command terminates.

Syntax and Semantics:

Refer to the COMMAND description

More than one COMMAND can be specified.

The command is called with No positional parameters:

SRC Definitions

Purpose:

To associate a file-extensions with an audit program (like SCA) and provide the necessary information in order to be able to execute that audit program (executable or script).

Syntax:

SRC src_type-list

OUT_TYPES = out_type-list

INC_FORMAT = [ env_type ] printf-format

SYSINC_FORMAT = [ env_type ] printf-format

FLAG_FORMAT = [ env_type ] printf-format

SYSFLAG_FORMAT = [ env_type ] printf-format

MULTI_SRC = multi_src_type [ printf-format ]

COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition

...

Semantics:

OUT_TYPES

List of mandatory output-types
The first one is considered the primary output-type
The primary output-type must start with a '.' (dot)
Secondary output-type(s) must contain a '.' (dot).
Note that if output-types do not start with '.' you may get name-clashes in Build-directory.
Files of these type(s) will be deleted before builder starts.

INC_FORMAT

Specifies information on the presentation of include-options (-I)

env_type

LIST | FILE

Specifies how the include-options will presented on the command-line.
LIST: In Environment Variable GBS_INCS
FILE: In a temporary file specified via EnvVar GBS_INCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.

printf_format

Specifies the printf format for include-options
It must contain a %s
e.g: -I %s for QAC.

SYSINC_FORMAT

Specifies information on the presentation of SYSTEM include-options (-I)
Items are taken from sysbuild/build/sysincs_src_type.gbs only.

env_type

LIST | FILE

Specifies how the include-options will presented on the command-line.
LIST: In Environment Variable GBS_SYSINCS
FILE: In a temporary file specified via EnvVar GBS_SYSINCS. The syntax is specified by the VIA_FORMAT in the SETUP definition.

printf_format

Specifies the printf format for include-options
It must contain a %s
e.g: -SI %s for QAC++.

FLAG_FORMAT

Specifies information on the presentation of flags (-D)

env_type

LIST | FILE

Specifies how the flags will presented on the command-line.
LIST: In Environment Variable GBS_FLAGS
FILE: In a temporary file specified via EnvVar GBS_FLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.

printf_format

Specifies the printf format for flags
It must contain a %s
e.g: -D %s for QAC++.

SYSFLAG_FORMAT

Specifies information on the presentation of SYSTEM flags (-D)
Items are taken from sysbuild/build/sysflags_src_type.gbs only.

env_type

LIST | FILE

Specifies how the flags will presented on the command-line.
LIST: In Environment Variable GBS_SYSFLAGS
FILE: In a temporary file specified via EnvVar GBS_SYSFLAGS. The syntax is specified by the VIA_FORMAT in the SETUP definition.

printf_format

Specifies the printf format for flags
It must contain a %s
e.g: -SD %s for QAC++

MULTI_SRC

Specifies that an audit-plugin can process multiple sources in one call.

multi_src_type

NO | YES | COMMA_LIST

Specifies how the source files will presented on the command-line.
NO: No multi-source. Single Source-specification
YES: Source-specificatons will be specified separated by spaces
COMMA_LIST: Source-specificatons will be specified separated by commas.

printf_format

Specifies the printf format for the source-specifications
Default is %s and may be omitted
It must contain a %s
e.g: -include **/%s for C++Test

COMMAND

Command to invoke the audit program.

Syntax and Semantics:

Refer to the COMMAND description

More than one COMMAND can be specified.

The command is called with the following positional parameters:

• $1 filename
  Without the file-type
  For MULTI_SRC this will be a constant: 'file_name'
• $2 in_file_spec
  May be absolute depending on SRC_ABS_PATH
  For MULTI_SRC this will be multiple filespecs
• $3 out_file_spec
  Relative path
  For MULTI_SRC this will be a constant: 'out_filespec'
• $4 out_file_path
  Relative path
• $5 out_file_type
  Including the dot.
• $6-$n ($*) Command-line flags.
  

The following additional Environment Variables are set and may be used:

• GBS_INCS
  Contains the include-statements specification as defined by INC_FORMAT
• GBS_SYSINCS
  Contains the include-statements specification as defined by SYSINC_FORMAT
• GBS_FLAGS
  Contains the flags specification as defined by FLAG_FORMAT Including:
  - Results of MODE, DEBUGGER, OPT and MAP
  - Values of flags_type.gbs files
  - Values in GBS_FLAGS_type
  Note that only the -D flags are included.
• GBS_SYSFLAGS
  Contains the flags specification as defined by SYSFLAG_FORMAT
• GBS_AUDIT_FLAGS
  Contains the content of EnvVar GBS_FLAGS_audit
• GBS_APP_name... and GBS_APP_name_VALUE...
  As specified in the sys.gbs file

SUMMARY Definition

Purpose:

To provide information on how to run the summary program (executable or script)

Syntax:

SUMMARY

COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition

...

Semantics:

COMMAND

Command to invoke the audit summary program.
It is not used if the Audit is an SCA Audit.

Syntax and Semantics:

Refer to the COMMAND description

More than one COMMAND can be specified.

The command is called with the following positional parameters:

• $1 sum_file_spec
  Specifies the .html output filespec

The following additional Environment Variables are set and may be used:

• GBS_APP_name... and GBS_APP_name_VALUE...
  As specified in the sys.gbs file

MAINT Definition

Purpose:

To provide the interface of an audit-related program that can be executed from the gbsmaint command

Syntax:

MAINT

COMMAND = [ ok_exit_values-comma-list ; ] command-definition

Semantics:

COMMAND

Command to invoke the audit program.

Syntax and Semantics:

Refer to the COMMAND description

Only one COMMAND can be specified.

The command is called with the following positional parameters:

• None

The following additional Environment Variables are set and may be used:

• None

Notes:

Examples of audit.gbs files:

File 1 (Basic reference)

#========================================================
#   [qac] audit.gbs
#========================================================
.plugin qac
.include <audit.gbs>

##EOF##

File 2 (Full specification)

#========================================================
#   [qacpp] audit.gbs
#========================================================

SETUP
    NICE_NAME       = QAC++
    VIA_FORMAT	    = -via %s

INIT
    SET_W   = QAC_EXEC => qacpp
    SET_X   = QAC_EXEC => qac++
    SET	    = QACPPHELPFILES => $GBSEXT_QACPP_PATH/help
    BIN_DIR =

SRC .cpp
    OUT_TYPES	    = .gout .met .err
    INC_FORMAT	    = -I %s
    SYSINC_FORMAT   = -SI %s
    FLAG_FORMAT	    = -D %s
    SYSFLAG_FORMAT  = FILE -SD %s
    COMMAND	    = 0,1 ; \
		      $GBSEXT_QACPP_BIN_PATH/$QAC_EXEC $GBS_INCS $GBS_SYSINCS $GBS_AUDIT_FLAGS $GBS_SYSFLAGS $GBS_FLAGS \
		          $2 $GBS_QACPP_FLAGS $* -outputpath $4 -n 1599
    COMMAND	    = exists $GBS_SYSTEM_PATH/sysaudit/$GBS_AUDIT/style_ALL.nrf; ; \
                      $GBSEXT_QACPP_BIN_PATH/pal qacpp $2 $GBS_PAL_FLAGS -outputpath $4
    COMMAND	    = exists $GBS_SYSTEM_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE ; ; \
		      $GBS_SYSTEM_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE qacpp $2 \
		          $GBS_INCS $GBS_SYSINCS $GBS_AUDIT_FLAGS $GBS_SYSFLAGS $GBS_FLAGS $*
    COMMAND	    = 0,1-9,99; \
		      $GBSEXT_QACPP_BIN_PATH/errdsp qacpp $2 $GBS_ERRDSP_FLAGS -outputpath $4 -file $2$5

SUMMARY
    COMMAND = ECHO SCA

MAINT
    COMMAND = >qac/bin/prqamaint.pl QACPP


##EOF##

Generic Build Support (GBS) - User Manual - The audit.gbs files