HOME Generic Build Support (GBS) - User Manual
Procedures

Description

In this section the essentials of some GBS procedures are described.
This is in no way a specification, final document or manual.
It shows the basic idea of what is possible in GBS.

Start-up the GBS environment

The 'gbs' command sets up the GBS environment.
The first time it is called, it will prompt the user for things like System Path and a SubSystem name. This information is remembered between logins.
Some main Environment Variables are defined:

$GBS_SYSTEM_PATH
$GBS_SUBSYS
$GBS_AUDIT
$GBS_BUILD
$GBS_TOOL
$GBS_COMPONENT

These Environment Variables form the basics of the GBS build-environment.
All GBS actions involve the currencies as indicated by these Environment Variables.
GBS maintains the contents of these variables.
Never change these Environment Variables yourself. Use the GBS commands to do that.

Navigating the directory structure

GBS is based on a system of currencies: current-System, current-SubSystem, current-Component, current-Build. etc. Whenever you make another System, SubSystem, Component or Build current (switch) the appropriate Environment Variables are set accordingly.
Builds (and Audits and Tools) are always current for a whole System.

Switch System

To switch to another System enter:
swr System-path or, if you do not know the path of the System enter: swr and you will be presented a list of Systems to choose from.

GBS_SYSTEM_PATH and additional Environment Variables needed for this System will be set.

Switch Subsystem

To switch to another Subsystem enter: sws SubSystem-name or, if you do not know the name of the SubSystem enter: sws and you will be presented a list of SubSystems to choose from.

GBS_SUBSYS and additional Environment Variables will be set.

Switch Component

To switch to another Component enter:
swc Component-name or, if you do not know the name of the Component enter: swc and you will be presented a list of Components to choose from.

GBS_COMPONENT and additional Environment Variables will be set

Switch Build

To switch to another build enter
swb Build-name or, if you do not know the name of the Build enter: swb and you will be presented a list of Builds to choose from.

GBS_BUILD and additional Environment Variables will be set

Switch Audit

To switch to another Audit enter
swb Audit-name or, if you do not know the name of the Audit enter: swb and you will be presented a list of Audit to choose from.

GBS_AUDIT and additional Environment Variables will be set

Switch Tool

To switch to another Tool enter
swb Tool-name or, if you do not know the name of the Tool enter: swb and you will be presented a list of Tools to choose from.

GBS_TOOL and additional Environment Variables will be set

Building

Building is the process of generating one or more items from a file in the 'src' directory to one or more files in the 'bld/build' directories.
Typical builds are: compilation, creating a library (archiving), linking.
The file-extension specifies the type of build that is required. (e.g.: *.c →C-compile)

The building process of a single file goes via specific, generic rules:

The source file is an argument in the command-line and is taken from the current 'src' directory.
More than one file from the 'src' directory may be specified. Wildcards are honoured.
The resulting files (e.g.) object-files will be written to the current 'bld/build' directories.
The name of the resulting file will be equal to the name of the source-file. Filename extensions may differ and will be specific for various platforms. i.e.:

name.c → name.obj
If the build fails, name.* will be deleted from the 'bld' Sub-Directories.
The include path (-I) will be assembled in the following order:
- The current 'loc' directory.
- The current 'inc' directory
- The 'inc' directories of the other Components within the same SubSystem:
  In the order and as specified in the 'scope.gbs' file
  or if not present:
  the alphabetical order as found in the comp directory.
- As specified by the contents of the inc_sourefiletype.gbs files, if present, in the order as found in the following directories, if present:
  - $GBS_COMPONENT_PATH/opt/$GBS_BUILD
  - $GBS_COMPONENT_PATH/opt
  - $GBS_SUBSYS_PATH/build/$GBS_BUILD
  - $GBS_SUBSYS_PATH/build
  - $GBS_SYSTEM_PATH/sysbuild/$GBS_BUILD
  - $GBS_SYSTEM_PATH/sysbuild
  This enables references to external stuff and from the 'import', 'res' and 'ext' areas.
The build-time options (-D) will be assembled in the following order:
- Fixed Build settings for the whole project as defined in the option-file in the 'sysbuild/build' directory.
- As specified by the contents of the flags_sourefiletype.gbs files, if present, in the order as found in the following directories, if present:
  - $GBS_SYSTEM_PATH/sysbuild
  - $GBS_SYSTEM_PATH/sysbuild/$GBS_BUILD
  - $GBS_SUBSYS_PATH/build
  - $GBS_SUBSYS_PATH/build/$GBS_BUILD
  - $GBS_COMPONENT_PATH/opt
  - $GBS_COMPONENT_PATH/opt/$GBS_BUILD
- If present: Build-time options as specified in the command-line
  This means that options specified on the command-line will win.

To be able to implement these rules and to take care of any limitations of a building step (like a compiler) scripts are used. I.e.: A compiler is never invoked directly, but always via its (dedicated) script. These scripts must reside in 'SYSGEN/build'.

Typical Build (Generation) commands are:
gbsbuild files-list
gbssysbuild SubSystem-list

Compiling

Compiling goes straightforward according to the rules specified above.

To compile a single file, enter: gbsbuild file.c More info: Generating Code

Building Libraries (Archiving)

For building a library, a 'glb-file' acts as the 'src' representative for the 'bld' library.
The glb-file contains a list of all object-files that will make up the library.
The glb-file also gives a name to the library. E.g.:

name.glb → name.lib

Using the rules as mentioned above, a script generates the library-build command needed to create the library, taking the object-files as specified in the glb-file.
A #include statement allows grouping of object-file-names. The search-path is the same as for other #includes
Note that the glb-file may also contain specific archiver options.
More info: glb/glk/glt Files and Generating Code

Linking

For linking, a 'glk-file' acts as the 'src' representative for the 'bld' executable.
The glk-file contains a list of all objects and libraries that will make up the executable.
The glk-file also gives a name to the executable. E.g.:

name.glk → name.exe

Using the rules as mentioned above, a script generates the link command needed to link the executable, taking the object-files as specified in the glk-file.
A #include statement allows grouping of file-names. The search-path is the same as for other #includes
Note that the glk-file may also contain linker-options like -L.
More info: glb/glk/glt Files and Generating Code

Testing

For (unit-)testing, a 'glt-file' acts as the 'src' representative for the test.
The glt-file contains the command-line with the name of the test-executable. Results go to a log-file in the 'bld'
The glt-file also gives a name to the log-file. E.g.:

name.glt → name.log

Using the rules as mentioned above, a script generates the test command needed to run the executable, taking the executable name as specified in the glt-file.
Note that the glt-file may also contain execution options
More info: glb/glk/glt Files and Generating Code

Generation by means of 'make'

With the information as supplied above 'make' files can now be generated and executed.

Typical commands are:
gbsmakemake
gbsmake build-file-name-list and gbssysmake SubSystem-list
To generate a single executable with 'make', enter: gbsmake myfile.exe
or, if the .glk file is in a different Component than the current-Component: gbsmake other_component:myfile.exe
For more information see: Generating Code

Exporting deliverables

Each Component has an optional export.gbs file in the Component-directory.
It specifies for each file in the Component that has to be exported, to which export directory it has to be exported, relative to the 'export'-directory and/or the 'res/SubSystem'-directory.
The command is:
gbsexport

Build-streams

Code may be generated for more than one build: Simulator testing and one or more build platforms.
Sometimes a single source-file generates for more than one build
A sequence of compilations for a specific build, with a specific compiler using the same set of compile-options, possibly followed by linking, resulting in a set of deliverables is called a stream or build-stream.
A total generation of the software-system requires the generation of all streams.
Streams can run in parallel and can so reduce generation throughput time.

Builders and File-types

Two mechanisms are used in order to prevent name-clashes (and overwriting of objects/executables):

File-type extensions
Multiple output directories (explained later)

Generic Build Support (GBS) - User Manual - Procedures

procedures.html

Contents