HOME
Generic Build Support (GBS) - User Manual
The tool.gbs files
Contents
Description
Example of a tool.gbs
Description
Purpose
The tool.gbs files are located in the GBS_SYSTOOLS_PATH/tool directories and are
used to define the particularities of a Tool.
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_SYSTOOLS_PATH/$GBS_TOOL
- $GBS_SYSTOOLS_PATH
Contents
SETUP definition
DEFAULTS definition
INIT definition
RUN definition
SETUP Definition
Purpose:
To define general stuff, valid for the whole definition set.
Syntax:
- SETUP
- NICE_NAME = nice_name
Semantics:
- NICE_NAME
- Specifies a more descriptive name of the Tool. It is used in messages.
- nice_name
- Free format (just do not make it too long)
DEFAULTS definition
Purpose:
To set Tool dependent defaults, overriding the GBS defaults
Syntax:
- DEFAULTS
- ACTION = action-definition
Semantics:
Refer to RUN semantics below.
INIT definition
Purpose:
To define derived Tool 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 '/'
RUN Definition
Purpose:
To provide information on how to run the Tool program (executable or script)
Syntax:
- RUN
- ACTION = actiondefinition
- ...
- COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition
- ...
Semantics:
- ACTION
- Specifies possible actions of the Tool. To be used as pos-arg, option or EnvVar
- action-definition
- action-definition := action_name... => option
- E.g.:
ACTION = API => api
ACTION = FULL => full
- Default is the first in the list
- COMMAND
- Command to invoke the Tool 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
- command | @user_script |
>gbs_audit_script | .gbs_script
echo_command | set_command
- 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 command on the next line by adding ' \' at the end.
The command is called with the following positional parameters:
- $1 selected_action
The option value of the DEFAULT ACTION
- $2 subsys_def_list
A comma-list of selected SubSystem definitions
subsys_def := subsystem:subsystem_type
- subsystem_type := GBS | MSVS | make | Other
E.g.: subsys1:GBS,subsys2:make,subsys3:GBS
- $3 out_file_spec
$GBS_SILO_PATH/tools/$GBS_TOOL/index.html
- $4 out_file_path
$GBS_SILO_PATH/tools/$GBS_TOOL
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
Notes:
None
Example of a tool.gbs:
File 1 (Basic reference - implicit default)
#========================================================
# doxygen_api [doxygen] tool.gbs
#========================================================
.plugin doxygen
.include <tool.gbs>
###EOF###
File 2 (Basic reference - explicit default)
#========================================================
# [doxygen] tool.gbs
#========================================================
.plugin doxygen
.include <tool.gbs>
DEFAULTS
ACTION = FULL
###EOF###
File 3 (Full specification)
#========================================================
# %TOOL% [doxygen] tool.gbs
#========================================================
SETUP
NICE_NAME = DoxyGen
INIT
BIN_DIR = bin
RUN
ACTION = API => api
ACTION = FULL => full
COMMAND = >doxygen/bin/doxygen.pl %1 %2 %3 %4
##EOF##
Copyright © Randy Marques of Randy Marques Consultancy - All rights reserved