Contents

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

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

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 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:

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-specifications will be specified separated by spaces
COMMA_LIST: Source-specifications 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_anyname...
  As specified in the GBS Customisation (Session) file

Notes:

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##