GBS Logo HELP HOME Generic Build Support (GBS) - User Manual
Procedures Bottom Doc. Button
Release RMC-06.02
(2024-04-29)

- Home
Getting Started
- Quick Start
- Release Notes
- Install Notes
- Create a GBS-WA/System
- FAQ
- Terms and Conditions (The Fine Print)
Basics
- Definitions & Acronyms
- Introduction
- Top Level Directory Structure
- Full Directory Structure
- Handling SubSystems & Steps
- Procedures
- Software Configuration Management Support
Manual Pages
- The Command-Line Interface
- All Commands
- The gbssys... Commands
- Generating Code (Building)
- Libraries & Executables and Testing
- Exporting Deliverables
- Auditing
- Customisations (Session)
- Customisations (User)
- Customisations (Admin)
- Integration with other Tools
- Plugins (Admin)
- Environment Variables (EnvVars)
User Files
- The GLKBT (glk/glb/glt) Files
Internal (.gbs) Files
- GBS Files - General
- audit.gbs
- broadcast.gbs
- build.gbs
- export.gbs
- flags_*.gbs
- subsys.gbs (.bat/.sh)
- incs_*.gbs
- owners.gbs
- sca_*.gbs
- scope.gbs
- site.gbs (.bat/.sh)
- steps.gbs
- switch.gbs (.bat/.sh)
- system.gbs
- tool.gbs
Various
- Development
- About
- Metrics Help
Full Documentation
- All Docs - Printable

Contents Bottom Doc. Button Top Document Button Down Section Button Blank

Description
Start-up the GBS environment| Navigating the directory structure| Switch System| Switch Subsystem| Switch Component| Switch Build| Switch Audit| Switch Tool| Building| Compiling| Building Libraries (Archiving)| Linking| Testing| Generation by means of 'make'| Exporting deliverables| Build-streams| Builders and File-types

Description Bottom Doc. Button Top Document Button Down Section Button Up Section Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Blank

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

Compiling goes straightforward according to the rules specified above.

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

Building Libraries (Archiving) Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 (Building)

Linking Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 (Building)

Testing Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 (Building)

Generation by means of 'make' Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 (Building)

Exporting deliverables Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Down Section Button Up Section Button Down Chapter Button Up Chapter Button

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 Bottom Doc. Button Top Document Button Blank Up Section Button Blank Up Chapter Button

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 Blank Top Document Button
procedures.html
Copyright 2021 © Randy Marques, Netherlands