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

File 1 (final build)| File 2 (debug build)

Description

Purpose

The build.gbs files are located in the GBS_SYSBUILD_PATH/build directories and is used to associate file-extensions with builders (compilers, linkers, etc) for a specific build.
Also the particularities of the builders 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.
The search path for the .include Directive is:
- $GBS_SYSBUILD_PATH/$GBS_BUILD
- $GBS_SYSBUILD_PATH

SETUP definition
DEFAULTS definition
INIT definition
SRC definitions (multiple)
...

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 Build. 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.: @%s for MVS or
%s (default)

DEFAULTS definition

Purpose:

To set Build dependent defaults, overriding the GBS defaults

Syntax:

DEFAULTS: MODE = mode-definition; OPT = opt-definition; DEBUGGER = debugger-definition; MAP = map-definition

Semantics:

Refer to SRC semantics below.

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 canonicalised (/.. 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 definition

Purpose:

To associate a file-extensions with a builder and provide the necessary information in order to be able to execute the builder.

Syntax:

SRC src_type-list: TYPE = generic_type [ include_re [ comment_re | c ] ]; ORDER = order-number; SRC_ABS_PATH = 0 | 1; INC_TYPES = inc_type-list; OUT_TYPES = out_type-list; OPT_OUT_TYPES = out_type-list; OUT_FILES = out_name-list; GLKB = env_type [ lib_spec ]; INCLUDE_INC = 0 | 1; INCLUDE_BLD = 0 | 1; INC_FORMAT = [ env_type ] printf-format; SYSINC_FORMAT = [ env_type ] printf-format; INC_ABS_PATH = 0 | 1; INC_SEARCH_STYLE = UNIX | STANDARD; FLAG_FORMAT = [ env_type ] printf-format; SYSFLAG_FORMAT = [ env_type ] printf-format; MODE = mode-definition; OPT = opt-definition; DEBUGGER = debugger-definition; MAP = map-definition; MULTI_SRC = multi_src_type [ printf-format ]; COMMAND = [ [ pre-condition ; ] ok_exit_values-comma-list ; ] command-definition; ...

Semantics:

SRC

Specifies the input-type.

May not be equal to '.glkb'

TYPE

Specifies the generic type of the builder.
Has consequences on how comments and includes are handled.

generic-type: gen | asm | c | glb | glk | glt
include_re: Regular expression specifying how include-statements are recognised; E.g.: For c the default is: ^\s*#include\s+[<"]\s*([^>"]+?)\s*[>"]
comment_re: Regular expression specifying how comments are recognised; E.g.: For asm the default is: ^\s*[;*/].*

Must be the first item in the list

ORDER

The Generation order

SRC_ABS_PATH

Some debuggers require an absolute src path to be able to find the source during debugging.

INC_TYPES

List of optional include-types
Used to determine the proper Template/Comment_char when creating a User-file with gbsedit
The SRC_TYPE is implicitly added to this list.

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.

OPT_OUT_TYPES

Additional (optional) output-types.
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.

OUT_FILES

List of (mandatory) output-files
These files will be deleted before builder starts.
This is a very tricky option because you can have only one source file of this type per Component and GBS will not check on this...

GLKB

Specifies additional information on glb, glk and glt processing.

env_type: LIST | FILE; Specifies how the GLKB output will be presented.
LIST: In Environment Variable GBS_GLKB
FILE: In a temporary file specified via EnvVar GBS_GLKB. The syntax is specified by the VIA_FORMAT in the SETUP definition.
lib-spec: empty | UNIXLIB; Specifies Unix-type library specification i.e.:
-llibname searches for all liblibname.glb_out_types

INCLUDE_INC

Specifies that Component INC-directories must be included in the include-path search.

Default = 1 for non GLKB types

INCLUDE_BLD

Specifies that Component BLD-directories must be included in the include-path search.

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 the C compiler.

SYSINC_FORMAT

Specifies information on the presentation of SYSTEM include-options (-I)
Used in those cases where the compiler headerfiles must be specified explicitly.
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: -I%s for the C compiler.

INC_ABS_PATH

Specifies that the include-search-path must be an absolute address

INC_SEARCH_STYLE

Specifies the order in which the Include-Paths are searched:

UNIX: The order in which the paths are specified, unless it is a it is a quotes-type include:
then first look in the directory of the including file
STANDARD: The order in which the paths are specified

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 the C compiler.

SYSFLAG_FORMAT

Specifies information on the presentation of SYSTEM flags (-D)
Used in those cases where the standard compiler flags must be specified explicitly.
Note that is normally not the case!
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: -D%s for the C compiler.

MODE

Specifies the options for FINAL, ASSERT, DEBUG and PROFILING
Useful for types: c

mode-definition: mode-definition := mode_name... => option; mode_name := FINAL | ASSERT | DEBUG | PROFILING; E.g.: MODE = DEBUG => -DDEBUG

OPT

Specifies the optimization
Useful for types: c

opt-definition: opt-definition := optimize_name... => option; optimize_name := YES | SPEED | SIZE | DEBUG | NO; E.g: OPT = YES SPEED SIZE => -O9

DEBUGGER

Specifies if debugging information must be included
Useful for types: c glb and glk

debugger-definition: NO => option (default); YES => option

MAP

Specifies if a memory-map must be created
Useful for types: glk

map-definition: YES => option (default); NO => option

In the option: any %1 (MSWin) or $1 (Linux) will be replaced by the file-spec of the map-file.

MULTI_SRC

Specifies that a build-plugin can process multiple sources in one call.
Cannot be combined with GLKB types

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

COMMAND

Command to invoke the builder.

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
GBS_SYSFLAGS
Contains the flags specification as defined by SYSFLAG_FORMAT
GBS_GLKB
For GLKB types
Contains the GLKB lines
GBS_APP_name... and GBS_APP_name_VALUE...
As specified in the sys.gbs file

Notes:

None

Examples of build.gbs files:

File 1 (final build)

#========================================================
#   [mingw] build.gbs
#========================================================

SETUP
    NICE_NAME	= MinGW_cpp

INIT
    SET_W       = TEST => WIN32
    SET_X       = TEST => LINUX
    BIN_DIR	= bin
    SETPATH     = PATH => GBSEXT_MINGW_CPP_BIN_PATH% PATH

SRC .c
    TYPE	= c
    ORDER	= 1
    INC_TYPES	= .h
    OUT_TYPES	= .o
    INCLUDE_BLD = 1
    INC_FORMAT	= -I%s
    INC_SEARCH_STYLE = UNIX
    FLAG_FORMAT = -D%s
    MODE    	= ASSERT    => -DASSERT
    MODE    	= DEBUG     => -DDEBUG
    MODE        = PROFILING => -DPROFILING
    DEBUGGER	= YES       => -g
    OPT     	= NO	    => -O0
    OPT     	= SIZE	    => -Os
    OPT     	= SPEED	YES => -O3
    COMMAND	= GBSEXT_MINGW_CPP_BIN_PATH%\gcc -c -Wall -ansi %GBS_INCS% %GBS_FLAGS% %* %2 -o %3

SRC .cpp
    TYPE	= c
    ORDER	= 1
    INC_TYPES	= .hpp
    OUT_TYPES	= .o
    INCLUDE_BLD = 0
    INC_FORMAT	= -I%s
    INC_SEARCH_STYLE = UNIX
    FLAG_FORMAT = -D%s
    MODE    	= ASSERT    => -DASSERT
    MODE    	= DEBUG     => -DDEBUG
    MODE        = PROFILING => -DPROFILING
    DEBUGGER	= YES       => -g
    DEBUGGER    = NO        =>
    OPT     	= NO	    => -O0
    OPT     	= SIZE	    => -Os
    OPT     	= SPEED	YES => -O3
    COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\g++ -c -Wall %GBS_INCS% %GBS_FLAGS% %* %2 -o %3

SRC .s
    TYPE	= asm ^\.include\s+(")(.*?)" ^\s*#.*
    ORDER	= 1
    INC_TYPES	= .inc
    OUT_TYPES	= .o
    INC_FORMAT	= -I%s
    FLAG_FORMAT = -D%s
    COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\as --warn --fatal-warnings %GBS_INCS% %GBS_FLAGS% %* %2 -o %3

SRC .glb
    TYPE	= glb
    ORDER	= 2
    INC_TYPES	= .glb
    OUT_TYPES	= .a
    GLKB	= LIST
    COMMAND	= call GBSEXT_MINGW_CPP_BIN_PATH%\ar -rvs %* %3 %GBS_GLKB%

SRC .glk
    TYPE	= glk
    ORDER	= 4
    INC_TYPES	= .glk
    OUT_TYPES	= .exe
    GLKB	= LIST UNIXLIB
    INC_FORMAT	= -L%s
    MAP     	= YES => -Wl,-Map -Wl,%1
#    DEBUGGER	= NO  => "Wl,-s"
    COMMAND	= @mingw_glk.bat

SRC .glt
    TYPE	= glt
    ORDER	= 5
    INC_TYPES	= .glt
    OUT_TYPES	= .log
    COMMAND	= >ALL/gbstest.pl

##EOF##

File 2 (debug build)

#========================================================
#   [mingwd] build.gbs
#========================================================
.plugin mingw_gcc

.include <build.gbs>

DEFAULTS
    MODE     = DEBUG
    DEBUGGER = YES
    OPT      = DEBUG

##EOF##

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

build.html

Contents

Description

Purpose

General

Contents

SETUP Definition

Purpose:

Syntax:

Semantics:

DEFAULTS definition

Purpose:

Syntax:

Semantics:

INIT definition

Purpose:

Syntax:

Semantics:

SRC definition

Purpose:

Syntax:

Semantics:

Notes:

Examples of build.gbs files:

File 1 (final build)

File 2 (debug build)