HOME
Generic Build Support (GBS) - User Manual
The audit.gbs files
Contents
Description
Examples of audit.gbs files
Description
Purpose
The audit.gbs files are located in the GBS_SYSAUDIT_PATH/audit directories and are
used to associate file-extensions with audit-tools (QAC, QAC++ etc) for a specific audit.
Also the particularities of the auditing tools are defined.
General
Please refer to .gbs files: General information
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
INIT definition
SRC definitions (multiple)
...
SUMMARY definition
MAINT definition
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 define derived Target 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
Semantics:
- SET_W, SET_X & SET
- Specifies an Environment Variable.
- envvar_name
- Uppercase please
- envvar_value
- If placed between quotes (") it will be canonicalized (/.. solved) and on
Windows converted to a ShortPathName without spaces.
- SET_W is executed for Windows only.
SET_X is executed for Unix and 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 '/'
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
- 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 Target-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
- VARIABLE | FILE
- Specifies how the include-options will presented on the command-line.
VARIABLE: 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/target/bld_incs_src_type.gbs only.
- env_type
- VARIABLE | FILE
- Specifies how the include-options will presented on the command-line.
VARIABLE: 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
- VARIABLE | FILE
- Specifies how the flags will presented on the command-line.
VARIABLE: 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/target/bld_flags_src_type.gbs only.
- env_type
- VARIABLE | FILE
- Specifies how the flags will presented on the command-line.
VARIABLE: 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++
- COMMAND
- Command to invoke the audit program.
- pre_condition
- file_exists_condition | env_value_condition
- The command will only be executed if the condition is true.
- file_exists_condition
- [ ! ] exists file_spec
- env_value_condition
- variable_name_in_uppercase =|==|!= value
- ok_exit_values-comma-list
- Specifies the exit values for the command that are considered OK.
Range specification (3-5) allowed. Default is 0.
- command-definition
- build_command | @user_script |
>gbs_audit_script | .gbs_script |
echo_command | set_command
- build_command
- Single line command
- You may want to use GBSEXT_<plugin>_BIN_PATH
- user_script
- Search for in User-Audit and then GBS-Audit
- gbs_audit_script
- Relative from the GBS plugin/audit directory
- gbs_script
- Take from GBS_SCRIPTS_PATH
- echo_command
- ECHO any_text
- Prints any_text. EnvVars and positional parameters are replaced
- set_command
- SET variable_name_in_uppercase = any_value
- Sets the EnvVar. In any_value EnvVars and positional parameters are
replaced
Note that you can continue a long line on the next line by adding ' \' at the end.
The command is called with the following positional parameters:
- $1 filename
Without the file-type
- $2 in_file_spec
Relative path
- $3 out_file_spec
Relative path
- $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.
- pre_condition
- file_exists_condition | env_value_condition
- The command will only be executed if the condition is true.
- file_exists_condition
- [ ! ] exists file_spec
- env_value_condition
- variable_name_in_uppercase =|==|!= value
- ok_exit_values-comma-list
- Specifies the exit values for the command that are considered OK.
Range specification (3-5) allowed. Default is 0.
- command-definition
- command | @user_script |
>gbs_audit_script | .gbs_script
echo_command | set_command
- command
- Single line command
- user_script
- Search for in User-Audit and then GBS-Audit
- gbs_audit_script
- Relative from the GBS plugin/audit directory
- gbs_script
- Take from GBS_SCRIPTS_PATH
- echo_command
- ECHO any_text
- Prints any_text. EnvVars and positional parameters are replaced
- set_command
- SET variable_name_in_uppercase = any_value
- Sets the EnvVar. In any_value EnvVars and positional parameters are
replaced
Note that you can continue a long command on the next line by adding ' \' at the end.
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.
- ok_values-comma-list
- Specifies the exit values for the command that are considered OK.
Range specification (3-5) allowed. Default is 0.
- command-definition
- command | @user_script |
>gbs_audit_script | .gbs_script
- command
- Single line command
- user_script
- Search for in User-Audit and then GBS-Audit
- gbs_audit_script
- Relative from the GBS plugin/audit directory
- gbs_script
- Take from GBS_SCRIPTS_PATH
Note that you can continue a long command on the next line by adding ' \' at the end.
The command is called with the following positional parameters:
The following additional Environment Variables are set and may be used:
Notes:
None
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_ROOT_PATH/sysaudit/$GBS_AUDIT/style_ALL.nrf; ; \
$GBSEXT_QACPP_BIN_PATH/pal qacpp $2 $GBS_PAL_FLAGS -outputpath $4
COMMAND = exists $GBS_ROOT_PATH/sysaudit/$GBS_AUDIT/user_checks$GBS_SHELL_FILETYPE ; ; \
$GBS_ROOT_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##
Copyright © Randy Marques of Randy Marques Consultancy - All rights reserved